















                     The Roman Catacombs
                    BBS System for Linux
                           v.1.07
                       By Gregory Shaw
                       shaw@fmsoft.com                      Table of Contents
Reading this Document                                      5
Introduction                                               5
   Background                                              5
   Requirements                                            6
   Cost                                                    6
   Multiline capabilities                                  6
   External requirements                                   6
   Design decisions                                        7
   Where do I start?                                       7
Initial Configuration and Compilation                      7
   Adding the BBS User and BBS Group                       7
   Where to install?                                       8
   Unpacking the archive                                   8
   Installing Shadow Passwords                             9
   Selecting a different language                         10
   Selecting a language as a default                      11
   Compilation and Installation of the mSQL Database      11
   Compiling the System                                   11
   Adding the 'new' user logon                            12
   Adding the 'bbs user' group                            13
   Linux FAQs                                             13
Serial configuration                                      13
   Modem Recommendations                                  13
   System Serial Configuration                            13
   A warning about gettys                                 14
   Initial Logon                                          15
   Logon Scripts                                          16
   User Home Directories                                  16
   BBS Daemons                                            17
Further Configuration                                     17
   Access Control                                         17
     The Options (bbsinfo) File                           17
     Access Card Usage                                    20
     Automatic Validation                                 21
     Re-Validation                                        22
     Limiting Access to Specific Modem Lines              22
   Text files used by the system                          22
   Menus                                                  23
     Menu Definitions                                     23
     Detailed Menu Command Definitions                    28
     Menu Macro Definition                                31
     Menus in Color                                       32
   Files Areas                                            35
     Configuring Upload and Download Protocols            35
     Configuring Files Areas                              35
     CD-ROM Files Sections                                36
     Uploading and Downloading in Detail                  36
   Using the Chat System                                  37
     Chat Rooms:                                          38
     Broadcasts:                                          38
     Private One-on-One Chatting:                         38
     Configuration of the Chat Subsystem:                 39
     Using the Chat Subsystem:                            39
     Reconfiguring the ANSI terminal type:                40
     Limitations of the Chat Subsystem:                   40
   The Messages System                                    40
     Messages System Background                           40
     Features of the Message System                       40
     Warning                                              41
     Starting the Database                                41
     Database Creation                                    41
     Current Limitations                                  41
     Message System Configuration                         42
     Taglines                                             44
     Electronic Mail                                      45
     Message Area Moderation and Public Message Import    45
     Message Area Maintenance                             46
Security                                                  46
   How the BBS uses Unix security                         46
   Security Holes - external programs                     47
   Interfacing with External Programs                     47
   Using a restricted shell                               47
BBS Maintenance                                           47
   Backing up your BBS                                    47
   Database Backups                                       48
   SysOp Utilities                                        48
   Trimming Log Files                                     50
   User Maintenance                                       50
   Troubleshooting                                        51
     Watching the Logs                                    51
     Watching for Problems                                51
     Check your Security                                  52
Additional Information                                    52
   Accessing the BBS from the Shell                       52
   File Formats                                           52
     The Userlog                                          52
     Files Sections                                       54
     DOOR.SYS Format                                      54
Linking External Programs to your BBS                     56
   BBS Doors                                              56
     Installing the BattleField                           56
   Using UQWK for off-line Mail and News                  57
   How to connect to FIDONet                              57
   UUCP, Mail and News                                    57
Other Information                                         57
   To Do                                                  57
Expanding your BBS                                        58
   More than two serial lines                             58
   Multiple Machines and Large Setups                     58
     Compiling the BBS for multiple machines              58
     Monitoring through IP sockets                        58
Updating from a previous release                          59
   Updating from Rocat 0.75                               59
   Updating from Rocat 0.80                               59
   Updating from rocat-0.85                               60
   Updating from rocat-0.86                               60
   Updating from 0.90-0.92                                61
   Updating from 0.92                                     61
   Updating from 0.95/0.96                                61
   Updating from 1.0 to 1.02                              62
   Updating from 1.02 to 1.03                             63
   Updating from 1.03 to 1.05                             64
BBS revision history (and future)                         65
Conclusion                                                65
To Contact Me                                             66
   The Rocat Mailing List                                 66
Appendix A: The Rocat BBS List                            66
Appendix B: Programming Externals                         66

   Reading this Document
     When reading this document, please keep in mind the 
following items:

  I refer to the user as 'he' or occasionally 'she'.  I 
   treat them both as neuter in this case; my use of 'he' or 
   'she' is entirely arbitrary.  I understand that a user 
   (or the SysOp!) may be of any gender.
  I try to explain items as well as possible.  If it is 
   something tricky, I try to put more description into the 
   explanation.   

   Introduction
     Welcome to the newest (working) BBS package available 
for Linux!  The Roman Catacombs BBS offers the following 
features:

  A familiar BBS interface for those who do not understand 
   Unix.
  Batch upload and download through the use of external 
   protocols.
  Automatic user addition to the BBS
  A very configurable BBS with many levels of security and 
   access.
  Multiline capabilities
  Professional code quality with future maintenance in 
   mind.
  An integrated chat subsystem.
  Full error logging.
  Color
  Most, if not all of the features of the DOS BBS systems.
  An elegant design that allows many additional features to 
   be added without requiring a major rewrite of the code.
  A complete, unique, message system.
  A complete production quality Database package (via a 3rd 
   party)

And many many more features.


   Background
     I've been running a BBS since late 1987.  I started on 
Macintosh computers, and proceeded to write some externals 
for the BBS package that I was using.  I wrote one game and 
a couple of utilities, most of which were shareware, which 
brought in enough money to keep the habit going.
     In 1993, I got fed up with the Macintosh for two 
reasons:
          1.  Any failure on the part of the BBS (generally) 
          resulted in a system crash.  This made the BBS 
          very unreliable.
          2.  The software was very limited and didn't do 
what I wanted to do with a BBS.

     I started to set up a DOS based BBS system, but ran 
into many problems.  DOS wasn't built with a BBS (or any 
multiuser capability) in mind.
     At that point, I was doing serious software development 
under Unix (Interactive SysVr3.2 for the curious).  I was 
using C++, and thought that an object oriented design for a 
BBS would allow a lot of flexibility.  So, I started 
developing a BBS.
     I cut over to the BBS package late in 1993.  It was a 
bit bare, and full of bugs, but it was a usable BBS system.  
I loved how any error in the BBS (e.g. a crash) logged out 
the user, and reset the line for the 'next' caller rather 
than crashing the operating system.
     Late in the year, I got caught up in Linux.  One of the 
major problems with writing the BBS for Interactive Unix was 
the number of installations of the OS.  I didn't want to 
create a BBS for a very small market.  So, I cut over to 
Linux, and started the port.
     After a few months of pulling my hair out because POSIX 
is different than BSD and SVID (and there are a few gaps in 
POSIX), I worked around most of the problems caused by 
POSIX.  
     From that time until the present, I've been adding 
features to the BBS.  I consider the BBS to be very 
reliable; I currently run a 3 line BBS with the software.
     Of course, I don't claim that the BBS is bug free.  Far 
from it!  I do claim, however, that the BBS is an excellent 
solution, and offers many options to a person wanting to 
setup a reliable, feature filled  BBS.

   Requirements
     The BBS has very few requirements, machine wise.  Most 
of this has to do with Linux.  If you can get Linux to run 
on your machine, and you've got a modem, you can generally 
use the Rocat system.  The basic requirements are:
     386 or better (preferably a DX)
     Modem
     Development system installed (GNU c and c++) (for 
compiling from scratch)
     5 megabytes of free disk space
     Familiar with basic Linux (Unix)
     TCP/IP installed (minimally)
     Root privileges
     Man pages installed
     The Linux  Frequently Asked Questions and HOWTOs 
available.

Not required, but nice:
     8 megabytes RAM or better (for compilation)
     A 486 or better processor (for the chat system)


   Cost
     The Rocat BBS and the mSQL database that ships with it 
is not free.  Both software packages are shareware, and, as 
such are expected to be paid for.  To register the BBS, 
print the file /bbs/docs/registration.ps (or .txt if you 
don't have a postscript printer), fill it out, and send in 
$100.00 to the address noted on the form.  Note that the 
database must be licensed separately (if applicable), as I 
am not the author, nor a partner of David Hughes.  See the 
mSQL database documentation for more information 
(/bbs/src/msql-1.0.14/doc).  Note that continued use of the 
software beyond a trial period (one month) represents theft.  
I know that I can't enforce payment for this BBS.  However, 
most SysOps are honorable people.  I trust their judgement.  
If you feel the software is worth $100.00 (US), please send 
in the registration.  The fee will be used to purchase 
additional development equipment for further BBS development 
(and there is a lot of BBS left to develop).   (the 
equipment currently used for development is far from top of 
the line)
     The BBS will remain free to non-profit entities.  
Should you operate such a group (a student Linux users 
group, for instance), simply send in the registration form 
with a note that you're a non-profit entity.
     When I receive your registration, I will send back a 
sentence you specify along with a key that will show to the 
world that your BBS is an officially supported Rocat system.
     Note that the rocat BBS requires the mSQL database.  If 
you cannot pay for the BBS (and are required to by the mSQL 
license), please stop right now.  I will not promote piracy.
 

   Multiline capabilities
     Due to the inherent multi-user capabilities of Linux 
(Unix), it is possible to have multiple persons using your 
BBS at the same time.  Rocat was designed to introduce very 
little system load on your BBS.  In most cases, should you 
be using your machine for (real?) work, you will probably 
not notice that someone is using your BBS.


   External requirements
     External programs are a major part of any BBS.  Due to 
the flexibility available in editors, news readers and mail 
systems, most of this capability has been left out of the 
BBS, so that you can pick and choose your own 'flavor' of 
BBS.   The externals that are necessary are:
     editors (vi, emacs, pico, joe, ee ... pick your flavor)


   Design decisions
     I made some design decisions regarding this BBS.  In 
other words, I wanted the BBS to be what I envisioned to be 
the 'perfect' BBS for myself.  Some of the more esoteric 
features of some BBS packages haven't been built into Rocat 
simply because I didn't feel they were necessary for my BBS.  
Some of the critical design decisions were:

     The Linux (Unix) system is used whenever possible.  
This is due to the sophistication of the system (and those 
features) as a whole.  The following subsystems are not part 
of the BBS, but are expected to be used by the BBS:
         News (fido, Internet news)
         Internet Chatting (Internet Relay Chat (IRC))
         Download protocols (rz, sz, kermit, xmodem, etc.)
         Background processing (at, cron)
         Login facilities (getty, login, etc.)
         Modem control (flow control)
         Account Passwords

          The BBS uses a modified 'system()' function.  This 
assumes that the command executed is available and will 
behave properly (e.g. an external will not allow shell 
access)  This has been done to allow interfacing with 
external system commands (see above).  This is also a huge 
security hole, if used improperly.


   Where do I start?
     Configuring and administering a BBS is a lot of work.  
I can't emphasize this enough:  No matter how good the 
software, being a SysOp is a lot of work.  If you don't have 
a lot of time, you should stop reading this document and go 
do something that requires less time  (write an 
encyclopedia, for example).
     Still here?  Ok.  Let's say that you want to setup a 
minimal BBS right now.  Your boss (spouse?) is breathing 
down your neck with deadlines and requests that this be 
quick.  To setup a minimal BBS, follow the following section 
up to the bbsinfo section.  After that point, copy all of 
the menus from $BBSDIR/examples/menus to $BBSDIR/menus and 
you should have a working BBS.  This will give you a working 
BBS, however, I'd rather you not build a BBS with my menus.  
I've worked hard to establish a completely unique BBS; 
copies of my BBS running elsewhere detract from the unique 
nature of my BBS. (it's an artist-thing)
     Once you've got a working BBS, be sure to consult the 
other sections to the manual.  A basic BBS isn't what most 
people want; most people want a system that is unique to 
their personality (or at least a unique system tailored to 
the task at hand).  
     I hope you enjoy what you're able to create from this 
BBS construction kit.  Being a SysOp is very frustrating, 
irritating and all-around work.  But, it can be one of the 
most rewarding jobs you'll ever have.  One message from a 
user thanking you for your wonderful BBS can make all of you 
labors worthwhile.

   Initial Configuration and Compilation

   Adding the BBS User and BBS Group
     A BBS administrator login and BBS administrator group 
is necessary for the BBS to be installed correctly.  Do the 
following steps to add the BBS user and group:
     1.  su to root
          su
          < enter root password >
     2.  Execute the groupadd program in /usr/sbin
          /usr/sbin/groupadd bbs
     3.  Look at the file /etc/group.  There is a number in 
the third field that is the GID (group id) for group BBS.  
Remember this number, you'll need it for adding the BBS 
Admin account.
          cat /etc/group
     4.  Execute the adduser program in /sbin.
          /sbin/adduser 
     5.  The name of the user should be 'bbs'.
     6.  The full name should be 'BBS Administrator', but 
can be anything you like (BBS Admin, etc.)
     7.  The GID should be the same as you saw in the 
/etc/group file above.
     8.  The UID (user id) can be anything, but I set mine 
up to start at 1000.  Enter 1000.
     9.  The home directory should be /bbs/admin.
     10.  The shell can be your favorite shell (I prefer 
/bin/tcsh).  You'll be using this account in the future, so 
use something that you're familiar with.
     11.  Enter a password you can remember.  Please don't 
make it simple; crackers LOVE to eat BBSs for breakfast (at 
3am).
     12.  In the unpacking step, the .cshrc and .profile for 
the BBS Administrator will be unpacked from the archive.

NOTE: All further steps (unless otherwise noted) should be 
done by the BBS Administrator account.  He will 'own' all of 
the files involved with the BBS, so you should get used to 
being 'him' (or 'her').  You may get to that user by the 
following command:
     su - bbs
     < enter BBS Administrator password >

     Or, alternatively, you may login as 'bbs'.

     (sub-note: don't do it until the BBS Administrator's 
account is available.  It won't be available until the next 
step is completed)

   Where to install?
     Installation of the BBS should be done on a separate 
disk partition, if possible.  This allows the BBS to exist 
in it's own 'area'.  The following is the setup of The Roman 
Catacombs BBS (my BBS):
     /    boot disk
     /usr another disk
     /bbs the BBS disk.

     The BBS disk contains everything relating to the BBS, 
executables, headers, files, etc.
     
     I'd recommend using a separate partition, if at all 
possible.  This will allow the BBS to use the disk caching 
of the device.
     If that isn't possible, pick a place to install the 
bbs, and make a symbolic link to /bbs.
     This is accomplished by the following steps:
          1.  mkdir my_bbs_dir
          2.  cd /
          3.  su (you need root privileges to make a link in 
the root directory)
          4.  ln -s path_to_my_bbs_dir/my_bbs_dir /bbs

     You'll also want to make sure that the BBS 
Administrator and the BBS group own the BBS home directory:
          chown bbs.bbs path_to_my_bbs_dir/my_bbs_dir


   Unpacking the archive
     The archive will come in a file named 
'rocat-X.YY.tar.gz' or 'rocat-X.YY.tgz', where X represents 
the major version and Y the minor version.  Both of these 
filenames represent the same file compression.  To 
uncompress:
     1.  su to the BBS Administrator (all files should be 
owned by the administrator):
          su bbs
          <enter the BBS Administrator password>
     2.  Copy the file to the BBS directory.
          cp /some_path/rocat-X.YY.tar.gz /bbs
     3.  Change directory to /bbs
          cd /bbs
     4.  Untar the BBS.  
          tar xvfoz rocat-X.YY.tar.gz
          Note:  If tar complains about 'unknown option z', 
you need to gunzip the file prior to untarring the file:
          gunzip Rocat.tar
          tar xvfo rocat-X.YY.tar
     5.  Change into the newly created directory.
          cd rocat-X.YY
     6.  Move the entire structure back one directory.
          mv * ..

     At this point, much of the BBS structure will be 
created.  Additionally, the BBS Administrator's setup 
information (.cshrc, .profile, etc) will be copied to 
/bbs/admin.  You'll want to log out and log back in as the 
BBS Administrator before continuing the process. 

   Installing Shadow Passwords
     If you are not interested in shadow passwords, please 
disregard this section, however, it is recommended that 
shadow passwords be used.  Security of your system will 
increase with the use of shadow passwords.  
     Prior to 1.07, the rocat distribution shipped with the 
shadow passwords source code.  However, this code was very 
outdated.  At this time, to get shadow passwords, do the 
following:
     1. Ftp to ftp.redhat.com (or a mirror)
     2.  Get two files, the shadow password suite (found in 
the contributed area, generally /pub/redhat/contrib/i386) 
and the source to the shadow password suite (in 
/pub/redhat/current/SRPMS/shadow*).
     3.  Install the shadow RPM binaries.
          su to root
          rpm -i -U shadow-utils-970616-1.i386.rpm (note 
that the version may be different)
     4.  Install the shadow source binaries.
          rpm -i -U shadow-utils-970616-1.src.i386.rpm (note 
that the name may be different)
     5.  Untar and build the shadow distribution.
          cd /usr/src/redhat/SOURCES
          tar xvfz shadow-970616.tar.gz
          cd shadow-970616
          make
          (long compile)
     6.  Copy the library to /usr/lib
          cd lib
          cp libshadow.a /usr/lib
     7.  cd to the rocat source.
          cd /bbs/src/rocat/src
     8.  Follow the directions in README.linux for 
installation.  The instructions are very straightforward.

     Notes:  
     2.  The following commands have .shadow added to their 
names.  Please copy these files to their 'normal' names:  
(This must be done prior to compiling and installing the 
BBS)
     Command        Path/Name
     /bbs/scripts/checkpw.pl  /bbs/scripts/checkpw.pl.shadow
     /bbs/src/rocat/anu.C     /bbs/src/rocat/anu.C.shadow
     3.  Follow the directions in the bbs Makefile 
(/bbs/src/rocat/Makefile) for target anu:

# for shadow passwords, comment the below line and uncomment 
the line with -lshadow
# and rename anu.C to anu.C.noshadow, and anu.C.shadow to 
anu.C
        $(CC) -o anu anu.o bbsipc.o errlog.o bbsinfo.o 
bbsutil.o -lm -lc
#       $(CC) -o anu anu.o bbsipc.o errlog.o bbsinfo.o 
bbsutil.o -lm -lshadow -lc


   Selecting a different language
     If your BBS is going to be english only, you may skip 
this section.  The BBS uses english by default.
     New to version 0.86 of Rocat is the ability to display 
text in any (available) language. 
     Prior to this time, changing the language that the BBS 
used meant going through the BBS and changing every string 
to the other language.  In 0.86, I've extracted all of the 
strings and replaced them with (hopefully meaningful) 
markers.  If you'll notice, there is a lang directory found 
under the /bbs and the /bbs/src directories.  This file 
contains a language file, english, that is used as the 
default language.
     If english is not your primary language, you may find 
other language files shipped with the BBS.  Please note that 
these files are shipped as a basis for persons to use with 
their own BBS.  Most of these files are out of date (I am 
unable to update them as I am not multilingual).  Due to 
this, you may want to look at this file and update it to the 
current Rocat revision.  

To create your own language file:
     1.  Copy english to <your language>
     2.  Go through the file, changing the strings to your 
language.  I'm sorry if the text isn't descriptive; it is 
descriptive in the context that it is used.  I've tried to 
explain where to find the text as much as possible.  Note 
that you can do whole ranges of text.  Where there are 
paragraphs in the file, I've tried to put them together so 
that you can edit them as you'd like.
     3.  Edit the file /bbs/config/languages
     4.  The file looks like the following:
          A|english|1|1.  English
          N|spanish|2|2.  Spanish
          ...
          You'll notice that this file is very close in 
format to the /bbs/config/protocols file.
          Field     What
          1.   The active flag.  An A means that the file is 
available and that the user
               should be able to select that language.  
Anything else is considered
               a comment.
          2.   The name of the file found in /bbs/lang.  The 
name must match exactly.  
          3.   The key that will select that language.
          4.   The text that will be shown to the user.
     5.  Due to the object layout within the BBS, there are 
a number of strings that cannot be dynamically selected.  
Edit the file bbsstring.h found in /bbs/src/lang.  The 
strings found in this file will be hard-coded into the BBS 
executable, so you'll want these strings to be as 'common' 
as possible.  Thankfully, there are only a few strings in 
the file.
     4.  Recompile.  The BBS should now be using the strings 
that you selected in bbsstring.h.  If you log into the BBS 
as a new user, you'll be asked to select a language.
     5.  Send the language file to me for inclusion into the 
BBS distribution.  Your file may be out of date with respect 
to BBS development, but it will save another person hours of 
configuration and will serve as a starting point for their 
language changes.
     Gotchas:
          Please watch out for the following problems when 
dealing with different languages.
          1.  The paragraphs in the languages file will have 
all whitespace around them deleted.  So, everything will be 
left justified when shown to the user.
          2.  If you're upgrading from 0.85, please see the 
section on upgrading.  The userlog file format has been 
changed.
          3.  Make sure that every string in the english 
file has a counterpart in your language file.  The BBS will 
continue to run if a string isn't found (It will send an 
empty string), but that can be very cryptic to the users.  
Note that the BBS will log errors of this sort if at all 
possible.

     New to 0.90 is a german language file.  A warning:  You 
MUST check the language file against the current revision of 
the english file.  I commonly add strings to the BBS while I 
am developing that are required for new sections of the BBS.  
As I stated before, I am not multilingual.  Due to this, I 
cannot update these files.  In other words, I'll include 
language files with the distribution, however, you use these 
files at your own risk.


   Selecting a language as a default
     You may want to forego the above and select a single 
language as your default language.  It doesn't need to be 
english.  To select english as your default language, edit 
bbs.h in the source area.  Change the 'undef' for the line 
that reads:
     #undef ONE_LANGUAGE_ONLY
     To:
     #define ONE_LANGUAGE_ONLY
     
     This will make english the only language available.  It 
will not allow a user to select a language.
     To configure this for a different language, go through 
the previous section, but change the following line in  
bbshdr.h. 
     #define DEFAULT_LANGUAGE "english"
     Change english to the filename of your language file.
     Note that you can change the language loaded by the BBS 
by default (as seen by a new user prior to being asked to 
choose a language) by changing the above to your language 
file.  This will allow a new user to see the language that 
they are familiar with upon connecting for the first time.
     Note also that changing the login.scr is necessary for 
language changes.  There are questions and other text within 
that script that need to be changed for the BBS to be seen 
in another language.

   Compilation and Installation of the mSQL Database
     See the note in the messages section of this document 
regarding restrictions on the mSQL database.  It is not 
freeware; it is shareware.  The rocat BBS requires this 
piece of software.       
     Rocat uses the mSQL database as the messages backend.  
A version of the database configured for the Rocat BBS 
system has been included with the Rocat archive.  To compile 
the database (you must be user 'bbs'):
     1.  cd to /bbs/src/msql-1.0.XX.  
     2.  Type 'make target'.  This will create the 
installation software.
     3.  cd to targets/Linux-X.X.X-iXXX (fill in the X's as 
necessary)
     4.  Type './setup'.  This will start the configuration 
process.
     5.  For the 'Top of install tree' question, type in 
'/bbs/msql'
     6.  Type 'n' for installation running as root.  It will 
run as user bbs.
     7.  Enter 'bbs' for the username it will run under.
     8.  Enter '/bbs/spool/db' for Directory for pid file.
     10.  At this point, it will grind for a while.  After 
it is done, type 'make install'.

     The database is now installed.



   Compiling the System
     Compiling the system is the easy part.  There is very 
little that needs to be done prior to compiling the code.  
There are some limits setup in the main header file and 
spread out here and there in the code.  For the most part, 
you won't need to mess with these settings.  If you really 
feel you need to muck around with the code, feel free.  Be 
warned, however, that the Rocat system is a very complex 
beast, and a fickle one, if changed indiscriminately.  Save 
an original copy of the BBS prior to making any changes.
     The following steps should result in a set of BBS 
executables:
     1.  cd to the src directory.
          cd src/rocat
     2.  Do a 'make depend'.  This will generate include 
file dependencies.
          make depend
     3.  Do a make. This should start the build process.
          make
     Come back in a couple minutes (on a Pentium with 20 
megabytes of memory) or a couple of hours (386SX-16 with 4 
megabytes of memory).  
     4.  Do a 'make install'.  This will copy the files to 
their destinations.
          make install
     5.  Change to the root user.
          su
          <enter root password>
     6.  Do a 'make install.anu'.  This will change the 
permissions on the 'anu' program to allow insertion of new 
user records to the passwd file.
          make install.anu

Note:  You will get some messages.  "Warning: ..." messages 
are just that; warnings.  An error is something that causes 
the BBS to fail to build ("Error: ...")

If you get errors, make sure of the following:

     1.  The development system is installed.  This includes 
GNU C, GNU C++ and GNU LIBG++.  Rocat is written in C++, and 
requires all of the C++ facilities to compile.  I recommend 
using the GNU compiler version 2.7.0 or higher.  In 
particular, the 2.5.8 release of GCC has bugs, and will not 
build the BBS.  You may check your compiler version by 
typing:
     gcc --version
     It should come back with the version of the compiler.  
In my case it is '2.7.0'.
     2.  Your path has the compilers in it.  'make' depends 
on your path to execute commands.  If you can't execute the 
command, make won't be able to execute it either.  Your path 
should contain (at least) /bin, /usr/bin, and 
/usr/local/bin.
     3.  The bbs user owns the entire Rocat directory 
structure.  If bbs doesn't own the directories, you won't be 
able to make any changes to the files and/or directories.  
(and generally, things will be pretty broken from here on)


   Adding the 'new' user logon
     The 'new' user logon must be added to allow users to 
log into your BBS for the first time.  To add the 'new' user 
logon, do the following steps.
     1.  su to root
          su
          < enter root password >
     2.  Enter the following command:
          useradd new -d /bbs -g bbs -s 
/bbs/scripts/login.scr -u 999
          You may use any number for the '999' number.  If 
999 is in use on your system, use a different number.  
(note: you should use a number above 500)
     3.  Delete the new users password.
          vi /etc/passwd
          /new:
          /\*
          x
          :wq!
     4.  Delete the information in the shadow file.
          vi /etc/shadow
          /new:
          dd
          :wq!
          
     If the information isn't deleted, the system will 
prompt for a new password for new -- but it won't allow it, 
basically not allowing anybody to log into your BBS for the 
first time!

   Adding the 'bbs user' group
          The 'bbs' user group must be added to keep the BBS 
user's group different from the 'BBS' group.  Many of the 
permissions on files are open to the 'bbs' group.  Users 
should be part of the 'bbsusers' group so that, for example, 
should they get a interactive shell, they can't destroy your 
BBS (inadvertently or no).  To add the 'bbs' user group, do 
the following steps.
     1.  su to root
          su
          < enter root password >
     2.  Edit the file /etc/group
          vi /etc/group
     3.  Add the following line:
          bbsuser::105:
     The group number (105) is entirely relative.  If 105 is 
in use on your system, use some other (unused) number.

As new users log onto the BBS, the addbbsuser will assign 
them to the bbsuser group.


   Linux FAQs
     Note:  In the below configuration and examples, I'm 
assuming that you're familiar with adding modems and 
configuring gettys.
     If you're not familiar with these items, I recommend 
the Linux FAQs.  They're invaluable information for those 
starting from scratch.  The FAQs are available as part of 
the Slackware distribution, and, should you install them, 
are found in /usr/doc/faq.  If you don't use Slackware, and 
have access to news, please look in the comp.news.answers 
newsgroup for Linux FAQs.

   Serial configuration

   Modem Recommendations
     Configuration of the modems is very important to the 
BBS.  If the modem isn't configured correctly, the BBS will 
never know that there is a user wanting to get onto the 
system!
     At this point, I'm using a ZyXEL U-1496+ on my BBS.  
However, I won't go into the configuration of the modem in 
detail; all you really need to know is the generic 
parameters that are necessary for the modem to work.  I've 
included the items that are generic to most modems in 
parenthesis at the end of the description.  The following 
are the key configuration items for your modem:
     A GOOD MODEM CABLE  (one that has all pins straight 
through is the best)
     Serial speed (DTE-DCE) speed should be locked at 
19.2Kbps or faster speed.  I lock my 28.8Kbps modems at 
115Kbps.  (see the serial-HOWTO for more information)
     Hardware flow control should be on.
     The modem should reset upon loss of DTR. (AT&D3)
     The modem should respond to carrier-detect (CD). 
(AT&C1)
     The modem should answer the phone on the first ring. 
(ATS0=1)
     If possible, error-free and data compression should be 
enabled.

     It's possible (and sadly, probable) that some of the 
above items will go by different names.
     Remember the speed you've locked the modem at.  You'll 
need it for the serial configuration.


   System Serial Configuration
     Serial configuration involves telling the computer 
where your modems are, and, what speed they're running at.  
At this point, I'm assuming you've got your modem(s) 
configured, and are ready to test the logon capabilities of 
your machine.
     Serial configuration involves the following steps:
     1.  Configuring the /etc/gettydefs file.
     2.  Turning on 'getty' processes for your modem.
     3.  Changing the /etc/issue file
     4.  Testing (if possible)

Configuration of the /etc/gettydefs file is easy.  Simply 
add the following line to your gettydefs file:

#  Modem locked at 38400:
#
38400# B38400 CS8 CRTSCTS # B38400 SANE -ISTRIP CRTSCTS #@S 
login: #38400

     Of course, if you are running at a different baud rate, 
you'll want to change all occurrences in the above file to 
the baud rate you wish to use.

     To turn on a 'getty' process for your modem, edit the 
/etc/inittab file.  In that file you should see something 
similar:

# Serial lines
s1:45:respawn:/etc/uugetty -t 90 ttyS0 38400
s2:45:respawn:/etc/uugetty -t 90 ttyS1 38400

     The above two lines are for COM1 and COM2 ports 
(DOS-style).  The above lines mean:
     1.  Spawn a 'getty' for the port ttyS0 running from the 
'38400' gettytab entry when in run level 4 or 5.  
     2.  If you get a carrier detect on the line, and 
nothing happens for 90 seconds, go ahead and hang up the 
phone.

     Note:  Linux goes into run level 4 or 5 by default on 
most configurations.
     Note:  Make sure that the files /dev/ttyS0 and 
/dev/ttyS1 exist.  They should look like this:

crw-rw-rw-   1 root     root       4,  64 May 21 19:43 
/dev/ttyS0
crw-rw-rw-   1 root     root       4,  65 May 21 19:43 
/dev/ttyS1

     If these files don't exist, the 'getty' program will 
error off, and you'll see errors on the console regarding 
the problem entry.  If they don't exist, see the Linux FAQs 
for creating device files.
     If you make any changes in the /etc/inittab file, be 
sure to issue a 'init q' command so that init will re-read 
the file and recognize the changes.
     Note:  For new users to log on (via the 'new' account), 
the tty line must be entered in the /etc/securetty file.  
The 'new' user runs as root, and without the securetty 
entry, root logon will be denied on that tty.  Do a 'man 
login' for more information.

     A default issue file can be found in /bbs/text/issue.  
Edit this file and copy it to /etc/issue to activate the 
message prior to logon.  

     If possible, you should have a friend log into your 
BBS.  If you have trouble, please reference the FAQs about 
turning on dialup services.


   A warning about gettys
     Many people have been frustrated by gettys.  Over the 
past year, I've found a few bugs in the gettys commonly 
available through Linux distributions.  Should you be 
frustrated by getty not working correctly (for whatever 
reason), please make sure you've got at least the following 
versions of getty:
     Program        Distribution
     getty          agetty-1.9.1a
     getty          getty-ps-2.07f
     mgetty         mgetty+sendfax-0.22

     If you are not sure about what versions you have (and I 
have no way to show what versions you have), please grab one 
of the above from 
ftp://sunsite.unc.edu/pub/Linux/system/serial.   You will 
save yourself much grief by using the latest versions.

   Initial Logon
     The initial logon process is documented below:
     1.  The user logs in as 'new'. 
     2.  The user is given a 'welcome to the BBS' message.
     3.  He is asked if he already has an account, and is 
unable to logon.
     4.  If this is the case, he's asked for some 
information, and is able to send mail to the SysOp of the 
BBS.  He is then logged out.
     5.  If the above was not the case, he's shown a file 
(/bbs/text/bbswelcome) describing the focus of the BBS.  
     6.  He is asked "Would you like to become part of the 
BBS?".
     7.  If anything other than 'Yes' (or something starting 
with 'y') is entered, he is logged out.
     8.  He is then asked his first name and last name.  
Checking is done from the file /bbs/text/badwords to make 
sure that there isn't an illegal word in his name.  This 
prevents logins of the form 'Doctor Death' and 'Joe Mama' 
from becoming usable logins.
     9.  His first name and last name are joined together to 
form a unique login ID for him.  It generally takes the form 
first inital and last name, but if you should have a logon 
of that nature, it will attempt to put additional first name 
characters along with the last name.  Note that only 8 
characters are used.  A sample:
     Name                Logon
     John Smith               jsmith
     John Smith (number two)       josmith
     Alfred Neumann           aneumann
     Alfred Neumann (two)          alneuman

Note:  It is possible to get in a loop.  If you have a short 
name, and all possible combinations have been used, it will 
cycle endlessly, trying for a combination.  Since this is 
very improbable, I've left this 'bug' in the system.
     10.  The user is given his login ID.
     11.  The user is then logged out.

When he logs in, the following happens:
     1.  Since there is no password for their account, the 
          BBS prompts for a password.  It loops until a 
          valid password is entered.
     2.  Since he is not found in the userlog 
          (/bbs/admin/userlog), the BBS asks whether he 
          wants to be part of the BBS.  
     3.  If not, he's logged off.
     4.  If the BBS supports multiple languages, he is asked 
          what language he uses.
     5.  He is asked for the city he is calling from.
     6.  He is asked for the state he is calling from.
     7.  He is shown a message describing what terminal 
          types are, and asked for the terminal type his 
          software supports.
     8.  He is asked whether his software supports color.
     9.  He is shown a file describing the editors available 
          on the system (/bbs/config/editors) and asked 
          which one he'd like to use.
     10.  He is asked for an alias.
     11.  He is asked how many lines are available on his 
          screen.
     12.  He is asked how many columns are available on his 
          screen.
     13.  He is prompted with the above information, and 
          asked whether it is correct.  If not, it goes back 
          to 3.
     14.  He is logged into the BBS (saved).  
     15.  He is shown the 'welcome' message.  
          (/bbs/text/welcome)
     16.  His personal information is displayed.
     17.  He is given an optional 'fortune'.
     18.  He is shown a bulletins menu that will allow him 
          to display any text files relating to the BBS 
          system.
     19.  At this point, the BBS runs the menu 'main', and 
          the BBS operates normally.


   Logon Scripts
     You'll want to edit your logon script to represent 
'your' BBS.  The script I am talking about is found in 
/bbs/scripts/login.scr.  There is a 'Welcome to The Roman 
Catacombs!' message found in there that you'll want to 
change to your BBS name.
     You'll also want to edit the '/bbs/bbs' file.  This 
file is the pipe that allows users to use the BBS 
effectively.  The file is as follows:

#!/bin/sh
#
# file to execute prior to starting main bbs program
#

# check for a password on the account.  If no password, 
force them to enter
# a password.
found=`fgrep $LOGNAME /etc/passwd | cut -f2 -d":" | wc -c`
while [ "$found" -le "2" ]
do
        echo We will now setup a password for your account.
        echo Please enter a password.
        passwd
        found=`fgrep $LOGNAME /etc/passwd | cut -f2 -d":" | 
wc -c`
done

IFS=""
PATH=/bin:/usr/bin:/usr/games:/usr/local/bin:/usr/ucb:/bbs/-
bin
export PATH
BBSDIR=/bbs
SYSOP=shaw
export BBSDIR SYSOP IFS
SHELL=$BBSDIR/rocat
export SHELL

# hack to get around the getty's problem with not setting 
CRTSCTS
# #*(@&#%(*&#.  Why can't ANYBODY figure this SIMPLE thing 
out?
# setup default terminal settings

stty sane
stty erase "^H" kill "^U" intr "^C" eof "^D"
stty hupcl ixon ixoff crtscts

exec $SHELL

     In the above file, you should change the SYSOP 
variable, and any other options you feel it is necessary to 
change.  I've got the editor set to 'ee' at this point, as 
it is an easy to use editor with excellent help.

   User Home Directories
     The users of a BBS must have some place to store their 
configuration files and any other miscellaneous files.  This 
is accomplished through the use of user directories.  The 
current implementation uses the following directory 
structure:
     /bbs/users - the root directory for BBS users.
          [a-z] - the first initial of the user's name.

An example:  If Alfred E. Neumann logs onto the BBS through 
the 'new' user logon, his home directory would be:
     /bbs/users/a/aneumann

     The initial logon scripts copy the following files to 
the user's account:
          /etc/stdprofile as $HOME/.profile
          /etc/stdlogin as $HOME/.login
          /etc/stdcshrc as $HOME/.cshrc

     Note that these files aren't used when the user has the 
BBS as his shell.  These files will only be used should the 
user get a shell (csh, bash, tcsh, etc) from you.
     Note also that these files don't exist as a standard 
Linux item.  You'll need to configure these scripts when you 
figure out how you want to handle shell-logins.  (e.g. users 
that log into the Linux (Unix) OS rather than the BBS)
     The next utility is a bit easier to digest.  The 
errlogd program is the BBS error logger.  You want to start 
this when the BBS is running.  It generates no output; it 
collects error and status messages from BBS processes and 
places them in /bbs/admin/bbserr.

   BBS Daemons
     The BBS comes with a number of background processing 
programs (daemons, pronounced DE-mons).  Most of these 
programs will be useful to you, to say the least.
     The first (and most important) daemon is the error 
logging daemon.  This program will log all acces to your 
BBS.  You will save yourself hours of grief by starting this 
prior to doing any further BBS configuration/debugging.

     To start the program, use the following command line 
(as the BBS Administrator):

     /bbs/bin/errlogd &
     
     The above starts the error logger and pushes it into 
the background.  See the below section for a more succinct 
description of the errlogd utility.  
     The other daemons are:

     Utility        Description
     rochatd        Chatting input/output
     ropchatd       Private chat input/output
     robcastd       Broadcasts and messages between users

     The other daemons are described later in the document.

     Here's a simple way to have the error logger started 
when your machine boots.  Put the following line at the end 
of /etc/rc.d/rc.local:

# start BBS daemons
su bbs -c /bbs/bin/rocat_daemons start

     You'll want to configure the first item in the bbsinfo 
file prior to executing the above program.  (see the next 
section for more information)


   Further Configuration
     The previous section showed you how to initially 
configure your BBS.  At this point, you (should) have a 
marginally working BBS.  However, there are many features 
that haven't been configured yet.  To make the most use of 
your BBS (and make your BBS better reflect what you want it 
to be), you'll want to continue through the reading through 
the rest of the section.

   Access Control

   The Options (bbsinfo) File
     Almost all options for the BBS program are found in the 
options file, /bbs/config/bbsinfo.  The file is a simple 
text file, with comments describing what the features are, 
and how to enter the features.  The features file found on 
the Roman Catacombs BBS follows:

# this file contains the bbs pathing and machine information
# setup as you desire
# it should be in the format: NAME <tab> value
# blanks and lines starting with # are ignored

# host where error logger is running

LOGHOST manwe

# host where sysop's watch program is running

WATCHHOST       manwe

# host where chat daemon runs

CHATHOST        manwe

# host where database is running

DATABASEHOST    manwe

# host where mail should be forwarded to (central mail 
server)

MAILHOST        manwe

# upload to download ratio      (7.0 is 7 downloads for each 
upload)
# negative numbers refers to how the ratio is done - if it's
# negative, then the ratio is enforced *BEFORE* the user 
downloads
# the ratio number of files (in the case of -7.0, he has to 
upload
# before he can download the 7 files possible.
# normal (aka positive) numbers refers to a normal upload 
ratio.
# meaning the ratio won't be enforced until after the even 
number
# of files has been downloaded (e.g. on the 8th file he 
wouldn't
# be able to download.
# set below to 1000 or some such number for no ratio.

RATIO   7.0

# default access level for a new user on the bbs

DEFACL  100

# default terminal type for new user on BBS

DEFTERM ansi

# default foreground
# available:  black red green yellow blue magenta cyan white

DEFFOREGROUND   green

# default background
# available:  black red green yellow blue magenta cyan white

DEFFOREGROUND   green

# default background
# available:  black red green yellow blue magenta cyan white

DEFBACKGROUND   black

# default color attribute
# pick only one
# available:  normal bold blink inverse

DEFATTRIBUTE    bold

# time that a user's time limit is good for.
# this is the amount of time that a user may use his 60 
minutes for.
# ex: if you set it to 24 hours, he gets 60 minutes every 24 
hours.

WAITTIME        12

# credit chat time with sysop?
# 0 for false, 1 for true

CREDITCHAT      1

# credit upload time?

CREDITUPLOADS   1

# the pager to use on your system (use 'more' or 'less' or 
whatever
# you like.  Note that the default user path must have this 
command
# available for it to be accessible.  (e.g. if you have 
'less' in
# /usr/local/bin, /usr/local/bin *MUST* be part of the 
default login path
# Note:  Fully qualifying the path won't work.  Only 15 
chars are allocated
# to the 'pager' variable.

SYSTEMPAGER     more

# the validation program to be used when the user logs on 
initially
# and when the user has been expired.
# set to 'none' to skip validation
# NOTES:
#       1.  it *MUST* be set to exactly "none" for no 
validation program
# to work correctly (no spaces after it, etc)
#       2.  a full path is recommended (if not required)

VALIDATION      none

# the default card color given to a user that has been 
validated
# note: this doesn't make sense if the above is 'none'

VALIDCARD       green

# login name of the sysop

SYSOP   shaw

# sysop's chat hours.  If the user hits 'chat' outside of 
these hours, he
# will be told you are not available and to leave a message.
# time is in military.  1900 is 7pm, 2200 is 10pm

CHATON  1800
CHATOFF 2359

# the below are the different things you can put on the 
command prompt
# line when at the end of a menu.
# turn on SHOWTIMELEFT to show the amount of time the user 
has left
# turn on SHOWVALIDKEYS to show the valid hot keys to the 
user
# USERPROMPT is the text that will prompt the user to hit a 
key.
# ex: with all turned on,
#  (15 Minutes left) Command? (a,b,d,i,k,t)  <--- user 
prompt here

SHOWTIMELEFT    1
SHOWVALIDKEYS   1

# set the below to 1 to show the caller the last 5 callers 
of the
# bbs

SHOWLAST        1

# the following determines the default card type for a new 
user
DEFCARD blue

# the following determine the amount of time and downloads 
that a user
# may have for different access levels.  Define as you wish.
# the format is:
# card color, access level, timelimit, additional flags,
# max downloads (k) per day, amount of downloads (k) per 
validation,
# days account is valid,
# total time available to account (hours),
# months until account expired,
# max files downloadable during period (hard number)
# time of day during which account available (0000-2400)
# flags is a hex value that will be added to the user's 
flags upon logon
# (e.g. for flag 12 on for additional access, it would be 
400)
# a -1 value in a limit field means 'don't enforce'
#
# color         acl     tl/day  flags   k/day   k/val   
day/val tot_tim 
mo/val dl/val  start    end
REDCARD         100     20      0       0       0       30      
20      1
200     0000    2400
BLUECARD        200     30      0       1000    10000   30      
20      -1
200     0000    2400
GREENCARD       200     60      0       1500    10000   30      
20      -1
200     0000    2400
WHITECARD       400     120     1       -1      10000   30      
20      -1
200     0000    2400
# I don't use the below.  Use them as you want.
GREYCARD        400     255     1       -1      -1      -1      
-1      -1
200     0000    2400
PINKCARD        600     0       0       0       -1      -1      
-1      -1
200     0000    2400
YELLOWCARD      700     0       0       0       -1      -1      
-1      -1
200     0000    2400
ROSECARD        800     0       0       0       -1      -1      
-1      -1
200     0000    2400
VIOLETCARD      900     0       0       0       -1      -1      
-1      -1
200     0000    2400
AZURECARD       1000    0       0       0       -1      -1      
-1      -1
200     0000    2400
BROWNCARD       1100    0       0       0       -1      -1      
-1      -1
200     0000    2400
PEACHCARD       1200    0       0       0       -1      -1      
-1      -1
200     0000    2400
# this is the sysop's card
BLACKCARD       10000   255     0       -1      -1      -1      
-1      -1
200     0000    2400

# check for mail?
CHECKMAIL       1
# location of the unix mail spool file
MAILSPOOL       /var/spool/mail
# minimum wait time between new mail checks (in seconds)
MAILCHECK       30


# 'talk' program for chatting with the SysOp
TALKPROG        talk

# show the user his 'fortune' upon logon?
SHOWFORTUNE     1

# Number of minutes of inactivity before user logged out
# 0 for no inactivity
INACTIVITY      5

# percentage 'fudge' factor for user while downloading.
# if at 10 (10%), it will give the user an additional 10% 
prior to aborting
# his download if his time has expired.
FUDGETIMELIMIT  5

# Max number of K the user may download with one batch
MAXK    2500

# Max number of K the user may download with one batch
MAXK_DAY        2500

# Max number of files the user may download in one batch
MAXFILES        10

# Should the BBS log the menu accesses?
# (good for debugging)
LOG_MENU_ACCESSES       1

# Should the BBS log external program accesses?
LOG_EXTERNALS           1

# Should the BBS log imported mail messages?
LOG_MAIL_IMPORT         1

# Should new users have their email imported to the BBS by 
default?
MAIL_FORWARD            1

# don't delete this line!

     As you can see, there are quite a few options.  Edit 
the above file however you wish.  Note that at this time, 
there are only 12 user card colors.  No more colors can be 
added without changing the code.

     See the section on account expiration/limits for more 
information about the card fields shown above..

     Note:  If you want to edit the user to give him 
additional access (say access 500 when he's using a blue 
card with access 200), the BBS will not drop his access.  
The cards are used as a minimal access value system only.  
If a value is less than a card's value, it will be set to 
the card's value.  If a value is higher than a card's value, 
it will be left alone.  This is to assume that you (the 
SysOp) have changed his access level for some reason.  This 
is true for all values found in the cards.

     


   Access Card Usage
     Rocat uses access cards to make grouping of users into 
catagories of access easier.  As you see below, there are 
many parts of the card structure found in the bbsinfo file.  
As you see below, each card has the following 
characteristics:

# color         acl     tl/day  flags   k/day   k/val   
day/val tot_tim mo/val dl/val  start    end
REDCARD         100     20      0       0       0       30      
2       12      200     0000    2400

In a broken down form:

Item      Description
color          Card color (not changeable)
acl       Minimum access level for this card
tl/day         Timelimit (minutes) per period (period 
defined by WAITTIME in bbsinfo)
flags          Additional flags that this card gives (in 
hex) 
k/day          Max downloadable K per period
k/val          The total amount of K the person may download 
while account is valid.
               This is a max limit - once the person has 
surpassed this, they will no longer be able to
               download.
day/val        The number of days the account is valid.
tot_tim        Total time available to the account (in 
hours).
mo/val         The number of months that the account is 
valid. 
dl/val         The total number of files a user may download 
while account is valid.
start          Starting time account may be used.
end       Ending time account may be used.

Notes:
   1.  I don't expect you to use all of the above.  I've put 
     the above in for those with more esoteric usage ideas. 
   2.  day/val and mo/val are individual items.  They are 
     assumed to be mutually exclusive.  That is, only one 
     may be used at any one time.  If both values are set to 
     some value, day/val is checked prior to mo/val.
   3.  k/val, tot_time, and dl/val are all cumulative 
     values.  Once these values have been exceeded, that 
     function will not be allowed.  Example: If the user 
     uses 8 hours, and tot_time is set to 8, they will not 
     be allowed to log in without being re-validated.
   4.  Validation requires that a validation program exists.  
     If the program does not exist (e.g. it is set to 
     'none'), the BBS will leave access at DEFCARD (shown 
     above in bbsinfo).   See the below section for 
     information on how automatic validation/expiration 
     works.
   5.  Any field set to -1 is ignored.  (e.g. no limit is 
     set)
   6. ACL and timelimit acces are cumulative.  If the ACL 
     and/or timelimit of the user are less than what their 
     card allows, their access will be updated.  If it is 
     not, their access will not be changed.  This allows the 
     SysOp to update access of a particular user without 
     having to resort to many different cards.
   7.  The start and end times are in military times.  0000 
     means midnight, 2400 means midnight the next night 
     (e.g. 0000-2400 means no restriction on time of call) 


   Automatic Validation
     New to version 1.0 of Rocat is the ability to 
automatically validate users.  This allows users to be 
checked automatically upon logon and to gain immediate 
access to the BBS.
     The validation program may be a script or a program.  
The script/program must return the following to the BBS:
     0         Validation  failed.
     1         Validation was successful; give the user a 
red card.
     2         Validation was successful; give the user a 
blue card.
     3         Validation was successful; give the user a 
green card.
     4         Validation was successful; give the user a 
white card.
     5         Validation was successful; give the user a 
grey card.
     6         Validation was successful; give the user a 
pink card.
     7         Validation was successful; give the user a 
yellow card.
     8         Validation was successful; give the user a 
rose card.
     9         Validation was successful; give the user a 
violet card.
     10        Validation was successful; give the user a 
azure card.
     11        Validation was successful; give the user a 
brown card.
     12        Validation was successful; give the user a 
black card.

     The validation program can do whatever you wish.  You 
can write a callback-verifier, a credit-card 
checking/authorization program or even the standard "fill 
out this form and I'll get back to you one day" many BBSs 
use.  The use of the validation program is up to you.


   Re-Validation
     Once a user has used up all of their resources (any or 
all), they must be re-validated.  This can be VERY tricky 
for the following reasons:
          1.  Once a user has exceeded absolute limits for 
their card, the bbs can not zero those limits.  Those  
fields are hard limits and not changeable.  They may only 
increase.
          2.  There is no (current) way to pass in the 
current access of the user.

     I only see this as a problem for those pay-oriented 
BBSs.  In that case, the BBS is leaving it in the hands of 
the validation program to 'do the right thing'.  It 
shouldn't be difficult to have the validation program offer 
a list of services (for different pay levels).  It would be 
up to the user at that point to figure out how much they've 
used and to buy more access than what they had previously.
     If this really becomes an issue, send me a message.  I 
might put an option into the BBS to call the validation 
program with the current card number (or something similar).

Notes:
     The validation system splits expiration into two 
distinct areas:
      Level    Description
      Critical The user is unable to access the BBS due to 
               expiration/limits.  Example: The user has 
               used all of their available time.
      Nuisance The user can access the BBS, but they are 
               unable to use some part of the BBS due to 
               some limit exceeded.  Example: The user has 
               used all of their download credit, but can 
               still access the BBS.

     In the above, critical means that the user is forced to 
re-validate.  In a nuisance setting the user may 
re-validate, but is not forced to re-validate.

   Limiting Access to Specific Modem Lines
     Many BBS systems offer the SysOp the option of limiting 
access to the BBS via specific lines.  Generally, this means 
that a multiple line BBS system limits the access to any 
lines other than the primary line to authorized users.  
(e.g. those who have paid for the BBS or are otherwise 
'special').  Rocat offers this capability also.   The 
following file defines the access of the BBS by line:

#
# Lines file: define access levels for different lines for 
the BBS.
#
# Format:  (similar to menu format)
#     tty#|security|security modifier|flags|flags modifier
#
# Example:
#       S10|200|>|2000|=
# 
# Means:  User must have access level above 200 and flag 14 
set to dial in
#         to the BBS using this line.
# 
# Notes:
#       The tty number is the dial in tty for the modem 
without the
#       /dev/tty.  Example:  /dev/ttyS0 (com1: to dossers) 
would be S0

     The above file is found in the bbs config directory 
along with the bbsinfo file.  Note that the file is case 
sensitive in the name of the TTY (e.g. linux uses a capital 
S in naming the serial ports).


   Text files used by the system
     Note:  All text files are found in /bbs/text.
     There are quite a few text files that are used 
regularly in the BBS.  They are:
     
     Filename  Contents
     badwords  those words deemed inappropriate for logon 
names
     bbsinfo        a short description of the BBS hardware 
(optional)
     bbswelcome     a short blurb on the BBS used prior to 
logging in the first time
     logoff         the logoff message given to the user 
upon exit
     newuser.msg    shown to the user on initial logon
     welcome   a mood-setting intro blurb shown on each 
logon
     
     All of the above files are customizable in any fashion 
you see fit.

     You'll end up modifying almost all of them.


   Menus

   Menu Definitions
     The menus are how a user interacts with the BBS 
program.  Because of this, the entire 'feel' of your BBS is 
how you setup the menus.  This is the place where you 
differentiate your BBS from other BBSs.  Well, enough 
soap-box.  Let's get started.
     When the BBS program starts, it displays the user 
information, the system messages, and then calls the 
mandatory 'main' menu.  This menu serves as the keystone 
menu; a place to start.
     Let me start with what a menu does.  Basically, a BBS 
menu shows the user a list of options, and, when an option 
is selected, tells the BBS to do something.  That something 
can be as simple as 'transfer to another menu', or as 
complex as 'call the external mailer program to send a 
message to the SysOp'.  It is all up to you on how complex 
you wish your menus to be.  
     A menu, as described above, is made up of 'options'.  
These options take the form of individual items, each found 
on an individual line.  A typical menu looks like the 
following:

0||||||| Roman Catacombs                                                 
Entry Vault
0||||||| 
------------------------------------------------------------
----------------
0|||||||
0|||||||                                   Exit
0|||||||
0|||||||                                      <G>
0|||||||                        ----------------------------
0|||||||                        H>elp
0|||||||                    <W> P>rivate Mail              
<E>
0|||||||          Art Studio -- R>egistration Instructions 
-- Computer Files
0|||||||                        U>tilities
0||400|>||||                        S<Y>sop's Area
0|||||||                        C>hat with SysOp
0|||||||                        ----------------------------
0|||||||                                      <S>
0|||||||
0|||||||                               News and Games
0|||||||
0||||||| 
------------------------------------------------------------
----------------
0||||||| <-> Previous Menu     <F> Feedback to SysOp   <G> 
Quick Logout
1|g||||||
3|-||||||
8|c||||||
2|y|400|>|||sysop|
2|e|||||computerfiles|
2|w|||||art_studio|
2|s|||||newsngames|
2|u|||||utilities|
21|f|||||elm -s feedback shaw|
2|p|||||mail|
10|r|||||reg.instr|
2|h|||||helptop|
2|h|||||helptop|

     The above was once main menu for The Roman Catacombs.
     The current TRC menu uses color, but to keep things 
simple, I'm using an older menu.
  
     Let's dissect a particular line:

0||||||| Roman Catacombs                                                 
Entry Vault

     In the above line, there is a number, followed by a 
number of pipe-letters (|), followed by some text.  In the 
above line, you find eight fields separated by the pipe 
letters.  The fields are:
     1.  Command Number
     2.  Key used to select item
     3.  Access level to see item
     4.  Access level modifier
     5.  Flags required to see item
     6.  Flags modifier
     7.  Optional data
     8.  The text for the item.

     In the above line, 0 is the command number (which is a 
text-only command), and fields 2-7 are blank (e.g. unused), 
and field 8 is the text to display.
     The user doesn't see anything but field 8.  If field 8 
is empty, he sees nothing.
     When a field is blank, it's assumed that everything is 
available.  For example, field 2 was the key to select the 
item.  Since it's an output only item, having a key there 
would be pretty useless, hence it's empty.  
     Let me define the fields in human terms:

Field     Formal Description       Use
1.   Command Number      Tell the BBS what operation to 
perform
2.   Selection Key            Key used to select menu item.
3.   Access Level             Access level required to 
see/use item.
4.   Access Flags             Define how to use Access Level
5.   Flags                    Flags necessary to see/use 
item (in hex)
6.   Flags Modifier           Define how to use Flags.
7.   Optional Data            (command specific usage)
8.   Text                Text to show user.

     Let me do a few more examples:

2|e|||||computerfiles|

     In the above line, 2 is the command (which means change 
to another menu), 'e' is the key used to activate the item, 
and all the rest of the fields are null.  Note how the 'e' 
goes with the item found above it:

0|||||||                    <W> P>rivate Mail              
<E>
0|||||||          Art Studio -- R>egistration Instructions 
-- Computer Files

     The user would select 'e' to go to the 'Computer Files' 
area (a menu in this case).  
     This is how menus work.  They define the text that a 
user sees, and, define what happens when a user activates 
that menu item.  

     Of course, there are times when you want certain users 
to be able to use a command, and, times when only you should 
be able to use a command.  Generally, these are defined by 
the security of the BBS.  There are commands that should 
only be executed only by the SysOp (or someone very 
trustworthy).  For this reason, there are fields 3 through 
6.  These fields allow you to define who gets to see and use 
what commands, based on access level and flags.  Let me 
define fields 3 through 6 a little better:

     Field 3 sets the access level for the command.  This 
and field 4 define the access level required to see/use the 
command.  An example:

2|y|400|>|||sysop|

     The above item defines a switch to another menu, the 
'SysOp' menu.  Of course, you don't want just anybody 
accessing this menu.  That is why the 400 and the '>' symbol 
are there.  The 400 is the access level (ACL), and the '>' 
means that the user's access level must be greater than or 
equal to 400 to see and access this menu item.
     By the same token, the flags required to see/use an 
item are selected the same way:

2|y|||32|=|sysop|

     The above item has flag 4 in the flags area and '=' in 
the modifiers.  This means that the user must have flag 4 
set before he may see/use the item.  Note that flags are 
written in hex, as they're consecutive powers of two. (and 
powers of two don't make much sense in decimal format)  Some 
powers and their respective flag numbers:

Flag Number         Hex
0              1
1              2
2              4
3              8
4              10
5              20
6              40
7              80
8              100
9              200
10             400
11             800
12             1000
13             2000
14             4000
15             8000
16             10000
17             20000
18             40000
19             80000
20             100000
21             200000
22             400000
23             800000
24             1000000
25             2000000
26             4000000
27             8000000
28             10000000
29             20000000
30             40000000
31             80000000

     The above are used to select individual flags.  To 
select multiple flags, simply combine the numbers.   For 
example, to select flags 10 and 25 for a command, use 
400+2000000 = 2000400.  Of course, you'll want to use the 
numbers in consecutive order; as typing lots of zeroes could 
get old very quickly.  The above are in hext to make the 
number relatively easy to type in.  For instance, the bottom 
number, if represented in decimal notation would be: 
4294967296.  Wouldn't that be fun to type?


     The fields will accept the following:

Field          Valid Contents      Meaning
ACL       0-32767
ACL Modifier   >              User must have ACL greater or 
equal to ACL
          <              User must have ACL less than ACL
          =              User must have ACL equal to ACL
Flags          0-80000000 (hex)              
Flags Modifier =              User must have flag set
          !              User must not have flag set

     Based on the above, you can have all sorts of 
permutations based on the user's capabilities.

     The official definitions for the command numbers (the 
first field) follows:

Command   Description                        Optional Data
0         Output only                        n/a
1         Log out of BBS                     n/a
2         Branch to another menu                  menu name
3         Exit to previous menu                   n/a
4         Search userlog for user information               
n/a
5         List users in userlog                   n/a
6         Display user information                n/a
7         Re-enter user information                    n/a
8         Chat with SysOp (via the 'talk' command)          
n/a
9         Change to another root menu (new to 0.85)         
menu name
10        Display a file (paged)                  filename
11        Display a file (not paged)                   
filename
12        Transfer to another menu directly (ignore stack)  
menu name
13        Chat with SysOp (through chat facility)      n/a
          SysOp must be logged into BBS
14        Send Email directly to the SysOp             n/a
15        Include another menu                    filename
16        Define a macro (see Macros)             macro 
definition
17        Undefine a macro (see Macros)           n/a
18-20          Unused (don't use)
21        Launch external program                 external 
program
22        Launch BBS-door external                external 
program
23-24          Not Used
25        List new files with option to download       files 
section
26        List new files without option to download         
files section
27        List all files with option to download       files 
section
28        List all files without option to download         
files section
29        Search for string in files area (w/ option)       
files section
30        "                                       " (w/o 
option)        files section
31        View detailed information on file            files 
section
32        Download file(s)                        files 
section
33        Upload file(s)                     files section
34        Delete a file that you uploaded (not implemented)
35        Download a single file (with ratio checking)      
full path and filename
36        Download a single file (without ratio checking)   
full patch and filename
37        Upload a file to the BBS without adding to a 
          files section                      directory to 
upload to
38        Upload to a file to '/bbs/tmp/$LOGNAME'           
n/a
          without adding to a files section.
39        Not Used
40        Search for users to edit/delete              n/a
41        Delete inactive users                   n/a
42        List inactive users                n/a
43        List users for edit/delete                   n/a
44        Invoke BBS monitor (not enabled)
45        Unused
46        Post a public message                   message 
section
47        Read public messages                    message 
section
48        Group read via group number             message 
group
49        Group read of selected sections              n/a
50        Select sections for command 49               n/a
51        Search for new messages in section since last call
message section
52        Search in section for text                   
message section
53        Search in selected sections for text              
n/a
54        Search in message group for text             
message group
55        Post a private message                  private 
message section
56        Read private messages                   private 
message section
57        Display section information             message 
section
58        Expire messages (SysOp)                 n/a
59        Show groups currently selected               n/a  
60        List sender and subject of messages in private 
mail private message section
61        Send an email to a particular address (no prompt) 
email address  
62        Delete all messages addressed to user in section  
section name
63-69          Not Used
70        Display chat server status (SysOp status)         
n/a
71        Display private chat server status (SysOp)        
n/a
72        Display broadcast server status (SysOp)      n/a
73        Display usage information for all rooms      n/a
74        Display usage information for one room       room 
number
75        Send a broadcast to all users (SysOp)        n/a
76        Send a broadcast to one user (SysOp)         n/a
77        Change the password (or ACL list) for a club club 
number
78        Connect to a club (asks for password)        club 
number
79        Connect to a dynamically created room        n/a
          (prompts for room number to connect to)
80        Connect to a public room                room 
number
81        Chat with another person privately           n/a
82        Create a dynamic room                   n/a
83        Edit the chat kill file                 n/a
84        Break into chat with a user (SysOp)               
n/a
85        Change the colors seen by other users in chat     
n/a

     Now that you've seen the entire list, you know what is 
available for your menus.  Let's go on to dissect the rest 
of the main menu:

0|||||||                        H>elp
0|||||||                    <W> P>rivate Mail              
<E>
0|||||||          Art Studio -- R>egistration Instructions 
-- Computer Files
0||||||| 
------------------------------------------------------------
----------------
0||||||| <-> Previous Menu     <F> Feedback to SysOp   <G> 
Quick Logout
1|g||||||
3|-||||||
8|c||||||
2|e|||||computerfiles|
2|w|||||art_studio|
21|f|||||elm -s feedback shaw|
2|p|||||mail|
10|r|||||reg.instr|
2|h|||||helptop|

     In the above menu fragment , you see a number of menu 
items.  Let me first say that I've taken the philosophy of 
breaking the text display and the commands into two 
different sections.  This allows me to see what the user 
sees without going into the BBS to check.  The first 3 items 
are the 'text' that is shown to the user to select an item.  
The last 9 items are the items that are available for 
selection.  
     Help is a menu transfer command (2) and will transfer 
the user to the menu 'helptop'.  
     Hitting 'w' will move the user to the 'art studio' (a 
place for picture files).  The name of the menu is 
'art_studio'.  This name is the same name found in the 
directory /bbs/menus.  It is assumed that all menus are 
found in the /bbs/menus directory.  
     A completely different command is command 8, which will 
execute the 'chat' program with the sysop's name.  At this 
time, I have it configured to use 'talk', but you may change 
this as you wish.  See the 'config' file section on how to 
do this.
     Specifically note command 21, which executes feedback 
to the SysOp.  This command is simply a 'execute external' 
command.  This command is passed to the system as if it were 
typed from and command line.  In this case, it is doing 'elm 
-s feedback shaw', which calls the 'elm' mailer (an easy to 
use mailer) with 'feedback' as the subject of a message to 
the SysOp (shaw).
     A special note about menu entry-exit.  The proper way 
to enter/exit menus is to use a command '2' to transfer to a 
menu, and a command '3' to return from that menu.  This is 
so that if you have many menus going to the same location, 
when you exit that menu, you return to where you were last.  
In computer terms, the menu system is a 'stack' of menus.  
When transferring to a new menu, that menu is put on 'top' 
of the stack.  When you exit that menu, the old menu is 
taken from the stack, returning you to the last previous 
menu.  Note that it is possible to transfer between menus 
using '2' commands all the time; however, it is not a good 
idea.  The stack will continue to fill, and when it hits 50 
(the current stack size), the program will probably die.  If 
you must do this, use menu command '12' rather than '2'.
     Please see the section on editing users for commands 
40-43
     A small sub-note.  It is not necessary for the stack of 
menus to be empty when the user logs out of the BBS.  They 
can log out at any time without causing problems with the 
BBS.  (In fact, they can drop carrier at any time without 
causing problems)


   Detailed Menu Command Definitions
The following offers detailed information on the menu 
commands available to the BBS:

Command   Description
0              This command dumps the contents of a command 
               to the screen. It's a 'dummy command' meant 
               only to display text on the screen.
1              Log out from the BBS.
2              Branch to another menu.  This pushes a menu 
               onto the 'menu stack' and branches to another 
               menu.
3              Exit to previous menu.  This removes the top 
               menu from the menu stack, effectively 
               returning the user to the menu he was 
               previously using. 
4              Search userlog for a user's name.  Display 
               resulting information.
5              List users in userlog sequentially.
6              Display current user's configuration 
               information (similar to that seen when the 
               user logs on)
7              Allow user to edit user configuration 
               information.
8              Use the unix command 'talk' to attempt to 
               chat with the SysOp.  The hours that the 
               SysOp enters in 'bbsinfo' are checked prior 
               to executing the command.
9              Change to another root menu (new to 0.85).  
               This allows a SysOp to have a 'main' menu 
               that would be used to get some information.  
               In particular, based on what the user selects 
               in the menu, the main menu transfers to 
               another menu.  (e.g. if you support multiple 
               languages, you could have the main menu be a 
               selection of what language to use.  Once they 
               select the language, they're transferred to a 
               new 'main' menu, which then becomes the base 
               of the system)
10             Display a file using the system pager 
               (configured in bbsinfo).
11             Display a file without paging text (good for 
               an ASCII download capability)
12             Transfer to another menu directly (ignore 
               stack).  This is good for a 'question' menu 
               that the user wouldn't want to see upon 
               returning back through the menu system.  
               Example:  I have an adult section in the BBS.  
               Prior to a person entering the section, I 
               display a menu that requires them to select 
               OK.  If they are not old enough, they may 
               select 'exit'.  Once they've gone past the 
               menu, however, the menu shouldn't be 
               displayed again, which this command allows me 
               to do.
13             Chat with SysOp using the BBS 'chat' 
               functions.  Note:  The SysOp must be logged 
               into the BBS for this command to work.  See 
               command '8' for a less restrictive 'chat'.
14             Send email (feedback) to the SysOp.  The 
               sysop's email address is specified in the 
               bbsinfo file.
15             Include another menu (new to 0.90).  This 
               allows a SysOp to build menus with pieces of 
               menus.  See the macro section for more 
               information.
16             Define a macro (new to 0.90) (see Macros)    
               macro definition
17             Undefine a macro (new to 0.90) (see Macros)  
               n/a
18-20          Unused (don't used)
21             Launch a program external to the BBS (a game, 
               newsreader, etc).
22             Launch a door (writes a door.sys file)
23-24          Don't Use (reserved)
25             List new files with option to download
26             List new files without option to download
27             List all files with option to download
28             List all files without option to download
29             Search for string in files area (w/ option)
30             "                                       " 
               (w/o option)
31             View detailed information on file
32             Download file(s)
33             Upload file(s)
34             Delete a file that you uploaded (not 
               implemented)
35             Download a single file (with ratio checking).  
               This allows a person to download a file that 
               isn't part of a files section (like a weather 
               map, or other frequently updated text file 
               that doesn't really belong in a files 
               section)
36             Download a single file (without ratio 
               checking)  This allows a person to do the 
               above, but it doesn't enforce ratios.  This 
               is handy for those files that need to be 
               downloaded regularly, but you don't care how 
               many times it is downloaded.  I currently use 
               this to download QWK packets for off-line 
               reading.
37             Upload a file to the BBS without adding to a 
               files section.  This is useful for uploading 
               a file to overwrite an existing file.  This 
               command should be used with caution, as it is 
               possible to overwrite a file using this 
               command.
38             Upload to a file to '/bbs/tmp/$LOGNAME' 
               without adding to a files section.  This is 
               handy for uploading QWK reply packets to the 
               BBS for processing/adding to news/email 
               sections of the BBS.
39             Don't Use (reserved)
40             Search for users to edit/delete.  This 
               command should be used only by SysOps and 
               sub-Ops.
41             Delete inactive users.  This command should 
               be used only by SysOps and sub-Ops.  Note 
               that this command does not delete users from 
               the /etc/passwd file.  The BBS would require 
               'root' permission to do this.  See the 
               /bbs/scripts directory for a script that 
               checks the userlog against the BBS userlog 
               file.
42             List inactive users.  This command should be 
               used only by SysOps and sub-Ops.
43             List users for edit/delete.  This command 
               should be used only by SysOps and sub-Ops.
44             Invoke BBS Monitor (not enabled in 1.0)
45             Don't Use (reserved)
46             Post a public message to a message section.  
               This will prompt the user for the message and 
               enter it into the database.
47             Read public messages.
48             Read public messages grouped into a 
               particular group.  See the messages section 
               for more information.
49             Read public messages in a group selected by 
               the user.
50             Select sections for command 49.
51             Scan for new messages in section since last 
               call.
52             Search for text in section.
53             Search sections.
54             Search Sections by group number.
55             Post private message.
56             Read private messages.
57             Display section information.
58             Expire messages in the message system.  This 
               will go through the entire message base and 
               expire messages older than the number of days 
               specified when the section was created.
59             Show groups currently selected.
60             List sender and subject of messages in BBS 
               mailbox.
61             Send email to someone.  The email address is 
               specified in the miscellaneous field.
62             Delete all messages in section addressed to 
               the user (typically used to delete all the 
               messages in the user's private mailbox)
63-69          Don't Use (reserved)
70             Display chat server status.  This command 
               causes the chat server to dump the usage 
               information contained within the program.
71             Display private chat server status.  This 
               command causes the private chat server to 
               dump the status information contained within 
               the program.
72             Display broadcast server status.  This 
               command causes the broadcast server to dump 
               the status information contained within the 
               program.
73             Display usage information for all rooms.  
               This is a handy command to allow users to 
               find those rooms that are in use.  See the 
               chat section for more information.
74             Display usage information for one room.  This 
               allows a user to display who is in a chat 
               'room'.
75             Send a broadcast to all users.  This is 
               primarily intended for the SysOp to announce 
               system events.  See the man page for 'wall' 
               for a 'better' broadcast command.  This 
               command could be used by users wishing to 
               announce something (e.g. the Star Trek 
               conference room is now open!  Go to dynamic 
               room 1142 to chat)
76             Send a broadcast to one user.  This could be 
               used by users that wish to send a message to 
               a friend.  Note that broadcasts don't reach 
               other users when they're downloading or in an 
               external application (like reading news).  
               Broadcasts are expired after some amount of 
               time has passed without a person to get the 
               broadcast.
77             Change the password (or ACL list) for a club.  
               This is primarily intended for the SysOp to 
               allow sub-Ops to maintain security lists for 
               private club rooms.
78             Connect to a club.  A Club room requires that 
               the person be on the access list (guest 
               list?), or, to know a password to get into 
               the room.  This command connects to a club, 
               and checks the list or a password prior to 
               giving access.
79             Connect to a dynamically created room.  This 
               allows a person to connect to a room 
               dynamically created by another user.  See the 
               chat system for more information.
80             Connect to a public room.  This connects a 
               user to a public chat room.
81             Chat with another person privately.  This 
               attempts to chat with another user.  It sends 
               a broadcast to another user, and, if the user 
               accepts, both users are transported to a 
               private chat room.
82             Create a dynamic room.  This allows a user to 
               create a dynamic room.  This could add 
               spontaneity to a BBS -- people could create 
               dynamic rooms to suite their 'whim'.  Note 
               that any BBS room not in use is de-allocated.
83             Edit the chat kill file.  This command allows 
               a person to edit their 'chat kill' file.  See 
               the chatting section for more information.
84             Break into chat with a user.  This allows the 
               SysOp to break into chat with a user 
               immediately, with no user intervention.  
               Handy for helping users having trouble.

Notes:
     1.  New to version 1.03 is the capability to display 
different text files to different users based upon their 
terminal type.  In particular, commands 10 and 11 (display 
file, paged and not paged, respectively) use the following 
to display a file:
          If a file exists with an extension the same as the 
user's terminal name, it is displayed rather than the 
filename itself.  
          If the above does not exist, the file passed in is 
displayed.  
     For example:
          If you wish to display 'welcome', but have 
separate ANSI and ascii versions, seperate the files into 
'welcome' and 'welcome.ansi'.  ANSI users will see the .ansi 
file while those without ANSI will see the 'welcome' file.

   Menu Macro Definition
     New to 0.90 is the following abilities:
       Inclusion of other menu files within a menu.
       Macro definition within menus

     The above allow you to build menus from sets of 
prototype menus.  For instance, you can have a standard 
header file with the common title of your BBS.  Add macro 
definitions, and you can create menus from prototypes that 
are unique and customized for each menu.
     For instance, there exists a header file in your menus 
directory:

0||||||| Roman Catacombs                                                         
\ma
0||||||| 
------------------------------------------------------------
----------------

     Note the \ma at the end of the first line.  This means 
to put what is in macro 'a' at this location when the menu 
is displayed.  
     If you use this file in your menus, as shown below, it 
will show up like it was in the menu from the start.  The 
user will never know what the BBS went through to build this 
menu for them.

16|a||||Macintosh Applications|
15||||||header|
0|||||||
0|||||||                        ----------------------------
0|||||||                        N>ew Files
0|||||||                    <W> L>ist Files
0|||||||         Apple Pie  --- S>earch for File
0|||||||                        I>nformation on File
0||199|>||||                        D>ownload file(s)
0||199|>||||                        U>pload File(s)
0|||||||                        H>elp
0|||||||                        ----------------------------
0|||||||
0||||||| 
------------------------------------------------------------
------------
----
0||||||| <-> Previous Menu     <F> Feedback to SysOp   <G> 
Quick Logout
1|g||||||
3|-||||||
21|f|||||elm -s feedback shaw|
3|w|||||appletop|
25|n|199|>|||macapps|
26|n|200|<|||macapps|
27|l|199|>|||macapps|
28|l|200|<|||macapps|
...

     Command 16 defines macro 'a' to be "Macintosh 
Applications".  Command 15 reads the file 'header' from the 
/bbs/menus directory at this point.  The menu then consists 
of the following:

0||||||| Roman Catacombs                                      
Macintosh Applications
0||||||| 
------------------------------------------------------------
----------------
0|||||||
0|||||||                        ----------------------------
0|||||||                        N>ew Files
0|||||||                    <W> L>ist Files
0|||||||         Apple Pie  --- S>earch for File
...

     The user sees the above (without the command structure, 
of course) and has no idea how the menu was built.  
     Note:  You'll soon run into the situation where you've 
got some amount of characters at the end of a line on the 
menu which wrap around, making the menu really ugly.  This 
is the one problem with the macro definitions:  If you've 
got spaces hard coded into the menu header and you define a 
set of text, it's possible that the text will be too long or 
otherwise, resulting in an ugly menu.  To solve this 
problem, I've added a right-justified movement command in 
the color area.  This will allow you to say "go to column 80 
and put the text there and make it fit to the right edge".  
     Another (big) Note:  Macro definition is not meant for 
simple text replacement only.  You can define macros within 
commands, macros within other macros ... macros anywhere.  
Basically, this could allow you to redefine your menu 
structure to something that is unique to your BBS.  This is 
really too big of a subject to jump into (using recursive 
macro definition is an art).  Let me give a few simple 
examples and I'll leave it to the Wizard BBS SysOps out 
there to stress the macro capabilities of Rocat.

     On The Roman Catacombs (TRC), I've got a lot of menus 
for files areas.  If you use a CD-ROM drive and/or disk 
space, you can create quite a few files areas in your BBS.  
Well, this means I've got a lot of menus that are basically 
the same:  You can look at files (using file section 
commands), download files, etc.  About the only thing 
different is the name of the files section itself.  This 
screams for the macro inclusion facility:

A current menu:

15|a|||||Main Menu|
0|||||||
0|||||||                        ----------------------------
0|||||||                        N>ew Files
0|||||||                    <W> L>ist Files
0|||||||         Apple Pie  --- S>earch for File
0|||||||                        I>nformation on File
0||199|>||||                        D>ownload file(s)
0||199|>||||                        U>pload File(s)
0|||||||                        H>elp
0|||||||                        ----------------------------
0|||||||
0||||||| 
------------------------------------------------------------
----------------
0||||||| <-> Previous Menu     <F> Feedback to SysOp   <G> 
Quick Logout
1|g||||||
3|-||||||
21|f|||||elm -s feedback shaw|
3|w|||||appletop|
25|n|199|>|||macapps|
26|n|200|<|||macapps|
27|l|199|>|||macapps|
28|l|200|<|||macapps|
29|s|199|>|||macapps|
30|s|200|<|||macapps|
31|i|||||macapps|
32|d|199|>|||macapps|
33|u|199|>|||macapps|
2|h|||||helptop|

     As you can see, I'm a bit behind in my menu system.  
Note, however, that the menu is very similar to a generic 
files menu.  You've got all of the same commands.  If you 
were to replace all instances of macapps with \mb, and 
define \mb to be macapps, you could extract the menu 
structure from the menu itself and have a files menu that 
was easily maintainable (after all, you only need one copy 
at this point).
     I'm sure you've got ideas of your own with respect to 
menu systems and how to use them.  If you find something 
really unique (a couple of things come to mind), send me a 
message.  I'd like to hear of unique ways to configure the 
menu system.
     One quick note:  At this point, there is no way to put 
the up and down character (|) in a macro.  After all, the 
BBS wouldn't be able to tell what was macro and what was 
command delimiters.  


   Menus in Color
     New to 0.90 are the color and movement capabilities of 
ANSI.  With these embedded color commands, you can colorize 
the entire BBS.  The following terms define whether ANSI 
codes are sent to the user:
     1.  The user is using the 'ansi' terminal type.
     2.  The user has enabled color in their profile.

     On older Linux installations, some 'ansi' installations 
didn't enable color.  To see if your 'ansi' has color 
enabled, do the following:
     1.  infocmp ansi
          This will dump the terminfo entry for the ansi 
terminal.  If there is no mention of color, or 'pairs' (of 
colors), or setf (set foreground) or setb (set background), 
color will probably not work in your configuration.  Follow 
the below to obtain a working color setup.
          If you find there is no 'infocmp' command, make 
sure that /usr/bin is in your path.  If it is, and you still 
can't use infocmp, you've probably got a very old Linux 
installation.  I'd upgrade before proceeding: new linux 
distributions have many many more capabilities (and bugs 
fixed) than old versions..  

     If your ansi terminal entry doesn't have color,  do the 
following commands to replace your 'ansi' entry with a more 
usable version.

     0.  su to root
          su
          <enter root password>
     1.  cd to /usr/lib/terminfo/a
          cd /usr/lib/terminfo/a
     2.  rename ansi to ansi.orig
          mv ansi ansi.orig
     3.  copy in the Linux console entry as the new 'ansi'
          cp ../l/linux ansi

     This will allow color while in the chat system.  If the 
above isn't done, chat will always be in black and white, 
regardless of whether the BBS is is color otherwise.  You'll 
also get many Out of Color Pairs error messages.

     The color commands are setup similarly to the macro 
definitions found in the menu module.  The color and 
movement commands use the following structure:
     \<character><color/formatting information>

     The BBS supports the following color and movement 
commands:
Command   Format              Use
f         \f<num>             Set foreground color
b         \b<num>        Set background color
l         \l             Set blinking
o         \o             Set bold (high intensity)
i         \i             Set inverse (reverse video)
u         \u             Set underline (monochrome only)
d         \d             Set dim (opposite of bold)
n         \n             Reset to 'normal' colors
c         \c<num><num>        Set foreground and background
a         \a<num>,<num>  Absolute movement
j         \j<num>,<num>       Right justified movement 

     Num in the above example refers to the color number.  
They are:

     1.   Black
     2.   Red
     3.   Green
     4.   Yellow
     5.   Blue
     6.   Magenta
     7.   Cyan
     8.   White

Notes:
     The foreground and background color command (\c) 
doesn't have a comma.  For instance, to set green foreground 
and black background, the command would be
     \c31
     Note that there is no space in the command.
     The absolute movement commands operate from the upper 
left corner of the screen, 0,0.  The X coordinate is first, 
and the Y coordinate second.  The upper right corner is 80,0 
and the lower left 80,25.  Use these numbers in the absolute 
and right justified movement commands.
     The right justified movement command is rather unique.  
It allows the SysOp to position text, right justified from 
some point on the screen.  For instance, if you had a 
string:
     This is text \j4,79 at position 80,4.
     The first part of the string would appear where the 
current cursor was.  However, the last part would start at X 
coordinate 79 and line 4.  It may be easier to think of it 
this way:  When you issue the command, the length of the 
rest of the line is subtracted from the X coordinate.  That 
position is where the text starts, with the last character 
of the text appearing at the coordinate that you selected.
     This command was created for one purpose:  In my menu 
system, I've got the menu name in the upper right of the 
screen.  If I define my menus with separate headers and 
trailers defining common items, I want to be able to put the 
title of the menu in the header as a macro.  Then, I define 
the macro in the (real) menu itself, so that it looks like 
each menu is unique.  However, I wanted the menu to look 
professional.  If I place the title macro in a certain 
position in the menu, I want the text of the macro to show 
up in the upper right corner, just as if I had placed it 
there manually.  An example from the previous section:

0||||||| Roman Catacombs                                                         
\ma
0||||||| 
------------------------------------------------------------
----------------

The above will place the macro in a position some number of 
spaces from the words 'Roman Catacombs'.  If I do the 
following, however, the text will always show up in the 
upper right corner:

0||||||| Roman Catacombs               \j79,0\ma
0||||||| 
------------------------------------------------------------
----------------

     This allows me to create 'custom' menus using menu 
templates.  Believe me, if you configure your menu system 
this way, it will save you lots of grief.  Some advantages:
       A change in the header and trailer will only need 
one change rather than a change to every menu.
       The number of menus you need will remain the same, 
however, defines for whole sections (and macros for those 
sections) will allow you to build a menu in a few lines 
rather than many large menus.

     The following menu is the current main menu for TRC:

16|a|||||Central Atrium|
15||||||header|
0|||||||
0|||||||  \o\c86Messages and Electronic Mail:\n
0|||||||    \o\c86<\f7A\f8> Messages and Internet News \n         
\o\c42Files Ar
eas:\n
0|||||||    \o\c86<\f7B\f8> Electronic Mail            \n           
\o\c42<\f7D\
f4> Linux (a free Unix-like OS)   \n
0|||||||    \o\c86<\f7C\f8> Group and Personal Chatting\n           
\o\c42<\f7E\
f4> Macintosh Files\n
0|||||||                                              
\o\c42<\f7F\f4> Microsoft
Windows  \n
0|||||||  \o\c85Roman Catacombs:\n                            
\o\c42<\f7G\f4> Pi
ctures \n
0|||||||    \o\c85<\f71\f8> User Environment Changes       
\n       \o\c42<\f7H\
f4> DOS/PC Files  \n
0|||||||    \o\c85<\f72\f8> User Information               
\n       \o\c42<\f7I\
f4> CD-ROM Files  \n
0|||||||    \o\c85<\f73\f8> Registration Information       
\n       \o\c42<\f7J\
f4> Files from Internet News   \n
0|||||||    \o\c85<\f74\f8> Roman Catacombs BBS 
Information\n       \o\c42<\f7K\
f4> Other Files\n
0|||||||    \o\c85<\f75\f8> Chat with the SysOp            
\n
0|||||||    \o\c85<\f7+\f8> Help with the BBS              
\n
0||400|>||||    \o\c85<\f70\f8> Sysop's Area                   
\n
0|||||||                                              
\o\c25Recreation:\n
0|||||||                                              
\o\c25<\f7L\f2> Games Area
\n
0|||||||
15||||||footer|
2|0|400|>|||sysop|
2|a|||||messages/news|
2|b|||||messages/email|
2|c|||||messages/chat|
2|d|||||files/top_linux|
2|e|||||files/top_macintosh|
2|f|||||files/top_windows|
2|g|||||files/top_pictures|
2|h|||||files/top_dos|
2|i|||||files/top_cdrom|
2|j|||||files/top_news|
2|k|||||files/top_other|
2|l|||||games|
2|1|||||rocat/environment|
2|2|||||rocat/information|
10|3|||||reg.instr|
2|4|||||rocat/rocat|
21|5|||||talk shaw|

     In the current distribution, I include a full set of 
the menus (less the adult menu areas) from TRC.  They are up 
to date and current.  They make great examples.  Please 
don't use them as your BBS, however.  I don't appreciate 
someone setting up an exact duplicate of my BBS.
     

   Files Areas

   Configuring Upload and Download Protocols
     A major part of most BBS systems is the ability to send 
and receive files.  Of course, this functionality is built 
into the Rocat BBS system.  The BBS supports all external 
protocols that are possible on Linux (Unix) systems.  
     Configuration of the files system involves two steps:
     1.  Configuration of the external protocols file.  
(/bbs/config/protocols)
     2.  Configuration of the main BBS files header file 
(/bbs/filehdr/bbs_files_hdr)

     A sample protocols files follows:


# this file describes the external protocols to be used by 
the bbs and
# the command to be used to invoke it.
# the format is:
# UPLOAD|command|needs filename (y or n)|key to select|text 
description for user
# DOWNLOAD|command|key to select|text description for user
# Note that if a command needs a filename, multiple file 
uploads are not
# allowed.  (this is the case with the below protocols.  If 
something
# different is found, then it can be changed)

U|rz|n|1|1. Zmodem
U|rb|n|2|2. Ymodem
U|rx|y|3|3. Xmodem
U|kermit -rb|y|4|4. Kermit

D|sz|1|1. Zmodem
D|sb|2|2. Ymodem
D|sb -k|3|3. Ymodem-1K
D|sb|4|4. Ymodem-G
D|sx|5|5. Xmodem
D|sx -k|6|6. Xmodem-1K
D|kermit -sb|7|7. Kermit

     As you see above, to add additional protocols, simply 
enter the upload and download commands as described in the 
above file.


   Configuring Files Areas
     Configuration of the main BBS files header file is also 
simple.  Another sample file follows:

#
# files header for the BBS.  Should contain one entry for 
every files area
# on the BBS
#
# format: filename [R|C] absolute_path_to_files.bbs 
sysop_name access_level down load_path upload_path 
age_to_delete_files long_name_of_area
#
# dashes fill non applicable positions

# dos files areas
[ dosapps R - shaw 0 dos/apps uploads 0 Dos Applications ]
[ doscomm R - shaw 0 dos/comm uploads 0 Dos Communications 
Programs ]
[ doscomp R - shaw 0 dos/compress uploads 0 Dos Compression 
Programs ]
[ dosdrivrs R - shaw 0 dos/drivrs uploads 0 Dos Drivers ]
[ cdromgames C /cdrom/dos/games/files.bbs shaw 0 dos/games 
uploads 0 Dos Games ]
[ dossounds R - shaw 0 dos/sounds uploads 0 Dos Sounds ]
[ dosutils R - shaw 0 dos/utils uploads 0 Dos Utilities ]


     This one is a bit more tricky.  The fields that make up 
the file are:

     1.  The name of the files section.  This is the name 
entered in field 7 of a menu.      This is also the name of 
the associated files header found in /bbs/filehdr when the 
section is a Rocat section.
     2.  The type of files section C for CDROM or R for 
Rocat.
     3.  The absolute path to the files.bbs file for CDROM 
sections.
     4.  The sysop's name.  Not used at this point.
     5.  The access level required to use the files section.  
Note that this is a minimal 
     number; if a user's access level is below this value, 
he will be denied access.
     6.  The relative path to the directory where the files 
are stored.  Note that you    must create this directory 
yourself.  The whole path is /bbs/files/relative_path.
     ex: dosapps is found at /bbs/files/dos/apps.
     7.  Age to automatically delete files found in the 
section.  This option is available 
     for material that is dated (such as ski reports) and 
that can be automatically 
     deleted after some period (in days).  Note that this 
operation isn't supported as 
     yet.
     8.  Name of the files section (as reported to users).  
This can be a very long 
     name, but it would be better if it were short.  Most 
programs limit it to about 20 
     characters.


   CD-ROM Files Sections
     As you can see above, the Rocat BBS system supports 
CD-ROM (read-only) files sections.  These sections are 
unique in that they never change (until you get a new 
CD-ROM) and they already have filenames and descriptions on 
the CD-ROM.
     Rocat will read the files.bbs that is found in every 
directory that has BBS readable files.  Simply enter the 
files.bbs as shown in the above example.  Note that a files 
section header file is not required, nor is it generated.
     There are some extenuating circumstances that Rocat 
checks for automatically:
     
     Should the CD-ROM be unavailable (you forgot to mount 
it or you have another CD-ROM online in it's place), access 
of the CD-ROM section will generate a message to the user 
telling him that the section is unavailable. 
     Uploads are not possible for CD-ROM sections.   I have 
made the assumption that you have your own files sections 
that would be used for uploading files that would reside in 
that section.
     The fileutil program, when scanning sections skips 
CD-ROM sections.  

     Other than that, CD-ROM filesections operate as they 
would with a Rocat files section.  


   Uploading and Downloading in Detail
     Uploading and download to/from the BBS is meant to be 
as transparent as possible.  However, it may not be obvious 
how this is accomplished.  In an effort to explain, this 
section describes in detail how the user downloads and 
uploads.

     A typical downloading session follows:
     The user lists files in a files section.
     He sees a number of files he's interested in.  He 
'Marks' the files for download.
     He then hit's 'Download'.  He is given a list of the 
files he has marked.  
     He then is given the list of protocols on the system.  
He selects the protocol he wishes to use.
     The download commences.  Note:  at this time, all 
downloads are assumed to be successful.  This means that if 
the user downloads 5 files, yet only gets 1 downloaded 
successfully, he is marked for 5 downloads.  This error is 
due to external file transfer programs not returning any 
useful information as to how many files were actually sent.
     The user's information is updated accordingly to 
reflect the files (and size of the files) downloaded.

     Of course, the above is a simplistic view of how to 
download.  Behind the scenes, there are a lot of security 
features that must be satisfied prior to a download taking 
place:
     1.  The user must be able to download (via the menu 
option).
     2.  He must have enough K available (via his card 
color) to download the file(s).
     3.  He must keep his upload/download RATIO within BBS 
specifications.
     4.  He must not have more than MAXK of files selected 
for download.
     5.  He has the access level to access the files area 
(see files areas).

     Note that uploads are credited to the user's account 
(provided that option is selected via the options file).  An 
example:
     The user has a blue card.  This enables him to 40 
minutes on-line, and 500K of download space.  The user 
decides to download the following files:

Filename       Size
a_big_gif.gif       450K
another_big_gif          75K

     He would be denied the second file, because that would 
be over 500K of transfers.  Note that if he downloaded the 
450K file and waited the expiration time (12 hours in the 
example options file), he would be able to download the 
other file.

     Uploads are handled a bit differently.  Of course, a 
user can upload as many files as he wishes.  When the user 
wants to upload, he goes to the section he wishes to place 
the files, and selects the 'Upload' option.  The below steps 
then happen:

     1.  He is then prompted for a file transfer protocol.  
     2.  After he selects the protocols, a new directory 
     with the user's name is created in /bbs/tmp.  
     3.  The protocol is then called with the upload option.  
     4.  After the exit of the transfer program, the user is 
     asked whether the upload was successful.  
     5.  If the upload was not successful, the user is asked 
     whether to keep the partially uploaded files.
     6.  If the upload was successful, the user is prompted 
     for each uploaded file's description.  
     7.  As the file descriptions are entered, the files are 
     moved to the uploads directory (as defined in 
     /bbs/filehdr/bbs_files_hdr for the section).
     8.  If the 'credit uploads' option is turned on in the 
     configuration file, the user is    credited for upload 
     space and upload time.


   Using the Chat System
     New to version 0.95 is a chat subsystem.  This system 
allows a user to chat with other users on the BBS.  The chat 
subsystem is broken into 3 major parts:
         Chat rooms (public and club oriented)
         Broadcasts 
         Private one-on-one chatting.

     A note about chatting:  
          Chatting is a very complex subsystem.  It uses 
'curses', a terminal based interface in addition to a lot of 
inter-process communication.  Due to this, I don't recommend 
chatting for BBS systems running on less than a 486 
processor.  I've tried to optimize the BBS and chat daemons 
to require little resources, but the chat system simply 
needs more CPU.



   Chat Rooms:
          The BBS supports the use of chat rooms.  These 
come in three flavors:
              Public Chat rooms.
              Access controlled Chat Club rooms.
              Dynamically created Chat rooms.

     Public chat rooms are simple chat rooms configured into 
the menu system.  The user may enter or leave the chat rooms 
as they wish.  
     Chat Club rooms are public chat rooms that have either 
a list of users that may access the room, or, a password 
that must be entered correctly prior to entering the room.
     Dynamically created chat rooms are chat rooms that are 
created by users.  A user may enter a chat room number to 
create the room, and then send their friends mail (or a 
broadcast, if that is configured) telling them the new chat 
room number.  This was added to give the BBS a more 
'free-form' appearance.


   Broadcasts:
     Broadcasts are short, one line messages sent between 
users.  Broadcasts may be sent to a single user or sent to 
all users on the BBS.  Broadcasts are a way for one user to 
send a quick message to another user.  Some notes about 
broadcasts:
      Broadcasts are not guarenteed to make it to their 
destination.  If a user is using an external application 
(downloading, reading news, etc), they will not get the 
broadcast.  This is done so that one user cannot cause 
another user's download to fail, intentionally or otherwise.
      Broadcasts are expired after a period of time.  If a 
broadcast is a person-to-person broadcast, and the receiving 
person gets the broadcast, the broadcast is immediately 
dequeued.  If the broadcast isn't received within a certain 
time frame (configurable in the broadcast daemon), the 
broadcast is also dequeued.
      Broadcasts only work within the BBS.  If a user has 
shell access and is not in the BBS program itself, they will 
not get the broadcast.


   Private One-on-One Chatting:
     The BBS supports private chat between two persons.  
This is done through the creation of a chat room for those 
persons to chat.  This is done by invitation only.
     If a user wishes to chat with another person directly, 
they may select private chatting from a menu.  They are then 
asked whom they wish to chat with.  A broadcast message is 
then sent to that person, asking them if they wish to chat.  
They user is interrupted, and asked whether they wish to 
chat.  If they wish to chat, both users are then moved to a 
private chat room where they may converse privately.  If the 
user does not wish to chat the originating user is informed 
of their decision.
     Notes about private chat:
      Private chat uses broadcasts to initiate connections.  
See the broadcasts section above for broadcast limitations


   Configuration of the Chat Subsystem:
     You must edit the /bbs/config/bbsinfo file to configure 
your chat system.  In particular the CHATHOST line must be 
changed to the name of your chat server machine.

     If you want to use 'clubs' to control access to certain 
rooms, you need to edit the file /bbs/admin/clubfile.  The 
format of the file is:

club_number|"password"
or
club_number|name,name2,name3

     The two formats allow more flexibility when accessing 
the clubs.  If you have a list of names, anybody that is not 
on that list will be denied access to the club chat room.  
If you have a password (and the quotes are mandatory), it 
will ask that user the password for that room.  If the 
password isn't entered correctly, they will be denied 
access.  See the file for more information.
     Note that clubs aren't any different than any other 
room.  If you have a club chat room 10, for example, and use 
the 'enter public room' command (80) instead of the club 
connect command (78), it will not ask for a password.  The 
distinction is entirely up to you.

     It is not necessary to use all of the pieces of the 
chat subsystem.  If you don't wish to support broadcasts, 
you may leave that daemon out.  The chat daemons are the 
following:
     
Daemon         Description
rochatd        The public chat daemon
ropchatd       The private chat daemon
robcastd       The broadcast daemon

     The private chat daemon will not work without the 
broadcast daemon.  In all other sitations, the systems 
operate independantly, and do not require one another to 
operate correctly.  The daemons all use the error logging 
daemon (errlogd) as their logging mechanism.
     You may start the daemons at system boot time by adding 
the following commands to the file /etc/rc.d/rc.local

     # start the chat daemon
     su bbs -c /bbs/bin/rochatd &
     # start the private chat daemon
     su bbs -c /bbs/bin/ropchatd &
     # start the broadcast daemon
     su bbs -c /bbs/bin/robcastd &

     Note that the above should be started after the error 
logging daemon (errlogd).

     There is one optional file that you may configure to 
allow the BBS to be more friendly.  In 
/bbs/config/roomnames, you may 'name' your rooms.  The 
format of the file is such:

     room_number    room_name

     That is, the room number (as used within your menus) is 
on the left, separated by a space or tab from the name of 
the room.  See the file for more information.  This 
information is used when looking at room information.  When 
the user lists the users in a room, the name of the room is 
used, if possible.


   Using the Chat Subsystem:
     Use of the chat subsystem is very simple.  Enter the 
commands to access a room (or set of rooms) in the menus, 
make sure the daemons are running, and the chat system is up 
and running.
     For users, the most important part of the chat 
subsystem is their terminal type.  The chat subsystem uses 
'ncurses', a terminal control system.  If the user's 
terminal isn't a good implementation, or the system doesn't 
have an entry for that terminal in the terminfo(5) database, 
or the user doesn't have his package configured correctly, 
that user could have difficulty chatting.  The terminal 
interface software (ncurses) expects the terminal to behave 
by the specifications of that terminal entry.  If it does 
not, the screen can get really messed up through the use of 
cursor control characters.  See the terminfo(5) manual page 
for more information.


   Reconfiguring the ANSI terminal type:
     New to version 1.0 of the chat subsystem is the 
capability to display color.  Any user may pick any of the 
ANSI colors as the colors they wish to see as their own 
'chat' colors.  However, the ANSI terminal type, as shipped 
with Linux (Slackware 2.3 in particular) isn't especially 
accurate.  See the section on 'Colorizing the BBS' for more 
information.


   Limitations of the Chat Subsystem:
     The following limits are built into the BBS:
     30 Public chat rooms
     30 Private chat rooms
     10 clients possible per public chat room (300 clients 
total, potentially all in one room)
     
     You may edit the file "bbshdr.h" to change the above.  
Change the definition for MAX_CHAT_ROOMS.  All of the above 
will change automatically.  Simply recompile the BBS and 
reinstall.

     The Chat subsystem is a cpu-hungry set of programs.  
Caution should be used when creating a large chat system 
that the machine used as a chat server is capable of 
handling the load.  Some ideas on load balancing (for a 
large bbs system):
     Try to split the chatting into manageable chunks.  In 
particular, in a large, busy BBS system, the machine used 
could become overloaded with both BBS and chatting.  Use 
another machine to handle the chat servers.  This will allow 
the BBS to run without being impacted by the chatting 
system.

   The Messages System
     The messages system allows users to receive, and send 
both email and public messages to other users on the BBS and 
on other systems.  

   Messages System Background
     Historically, a BBS - a Bulletin Board System, referred 
to the public message areas available to the users on the 
system.  These message areas were used as forums for public 
(and not so public) discussion.  Through these sections, 
users gained information from other users and talked about 
many current subjects.  Rocat didn't have a message system 
until 1.05.  With the 1.05 release, Rocat introduces a world 
class messaging system, along with a superior database 
product.   I believe your users will enjoy the unique 
messaging system and the ease at with which they're able to 
move around within the messages system.


   Features of the Message System
     The Message system includes the following features:

  A three level message selection system that allows users 
   to get to the messages they're interested in much faster 
   than traditional iterative methods.
  The capability to send new postings to a message area 
   moderator.  This allows a single person to authorize 
   messages for a particular area.
  Full security with respect to message areas.  Users may 
   not access sections that they are not authorized to see.
  Read only sections.  (for newsletters and other read-only 
   mediums)
  The capability to group areas for group reading.  This 
   works two ways:
    A user may select the areas they wish to see throughout 
   the entire message system.
    The SysOp may group similar sections together (say a 
   series of sections about cars) for a single section read 
   without the user having to iterate sections or group 
   sections manually
  Automatic import of both email and public postings into 
   the BBS.
  Full notification of new mail to the user.  
  A fully featured database backend using a subset of the 
   SQL standard.  The database may be used for more than the 
   message system (and will be used for more generalized 
   system storage in the future).
  Full database locking for all database access.
  Forwarding of all email to the Linux system's sendmail 
   system for proper mail delivery.
  Full failed email bounce capabilities for undeliverable 
   messages.
  Automatic deletion of messages after some period of time 
   specified by the SysOp (per section).
  A full tagline system that allows a large amount of 
   flexibility with respect to different taglines available 
   to different message areas.
  A backup script that extracts the database nightly and 
   cycles on a monthly basis. 
  Nightly reports that detail new messages and 
   expired/deleted messages.

   Warning
     The mSQL database is not freeware.    I cannot force 
you to pay for it.  However, I do expect you, as an 
honorable SysOp (dishonorable SysOps don't remain SysOps for 
long) to pay for the database if required to do so by the 
mSQL license document.
     I do not promote piracy, however, I know that I have 
worked very hard on this BBS, as have many other authors on 
their own software (mSQL in particular).  Please make sure 
that the author gets the reward requested for his labor.


   Starting the Database
     The database daemon (msqld) must be started prior to 
accessing the database.  The following command will start 
the database:
     /bbs/msql/bin/msqld &

     You'll want to start the daemon prior to creating the 
database itself, as well as upon startup of the machine.  
For now, type the above command manually.  The rocat_daemons 
script will start the database when the machine boots.  (you 
did install it in the boot scripts, didn't you?)
     Ignore the message about the missing acl file.  It 
isn't necessary.  Send me an email if you're particularly 
paranoid and want to create an ACL file.  The BBS has some 
unusual requirements regarding the bbs database and 
security.

   Database Creation
     Prior to accessing the database, you must create the 
database and the minimum tables.  To do this:

     1.  cd to /bbs/scripts
     2.  run the create_database script.  

     This will create the database and the minimal tables 
necessary for the database.

   Current Limitations
     There is one limit within the database at this time.  
Currently, the largest packet size for database 
communications is 32Kbytes.  This means that the maximum 
message length is approximately 31K, or 387 lines.  Until 
this limitation can be addressed, don't create sections 
above 387 lines maximum.  

   Message System Configuration
     The minimal database configuration does not include any 
message areas other than the private email table.  To create 
a message area:

     1. cd to /bbs/scripts
     2.  run create_table to create a message area.

     create_table, when run, will dump the minimal options 
for creating a new message area.  The format is:
     create_table section_name max_lines_per_message "Long 
Section Name"

     The above are the options to create_table.  However, 
there are many options to create_table that are not at the 
command line.  Most of these options don't change very 
often, so, rather than make you type a VERY long (error 
prone) line, I've placed the options and the documentation 
for the options in the file:

#!/bin/sh

# Filename:  create_table
# Description:  This script attempts to create an additional 
message base
#       table for the Rocat BBS system.
# Author:       Greg Shaw
# Created:      2/13/96

# BBSDIR set?
if [ "$BBSDIR" = "" ]; then
        echo Please run this script as user bbs.
        exit 1
fi

# right number of arguments?

if [ $# -ne 3 ]; then
        echo "USAGE: $0 <new_table_name> 
<number_of_lines_per_message> \"Long na
me of section\" "
        exit 1
fi

tablename=$1
textsize=`echo $2*80 | bc`

if [ $textsize -eq 0 ]; then
        echo number_of_lines_per_message must be larger than 
1
        exit 1
fi


# check for msql
if [ ! -x $BBSDIR/msql/bin/msql ]; then
        echo Please compile and install the mSQL package 
prior to executing
        echo this utility.
        exit 1
fi

# the following items are assumed not to change on a regular 
basis.
# however, to create a message area with different 
parameters, simply edit
# the following:
# (I wouldn't change the first 3)

# start at message 1 for the new section
HIGH_MESSAGE=1
# start at thread 1 for the new section
HIGH_THREAD=1
# 0 messages in section
NUM_MESSAGES=0
# section type:
# 0 - private message base
# 1 - Rocat message base
# 2 - fido message base (unused)
# 3 - usenet news message base (unused)
SECTION_TYPE=1
# access level to access
ACL=200
# flags to access
FLAGS=0
# I wouldn't change the below unless you're really sure you 
need them
# flags/access modifier: (bit mapped -- acl and flags or'd 
together)
# 0x00 - no modifiers
# 0x01 - user acl must be greater than acl
# 0x02 - user acl must be equal to acl
# 0x04 - user acl must be less than acl
# 0x0100 - flags must match
# 0x0200 - flags must not match
# convert the value to decimal for the value
# (e.g. 0x0100 = 256)
FAMOD=256
# is the section read_only?  (e.g. no postings by users)
READ_ONLY=1
# are anonymous postings allowed?
ANONYMOUS=0
# read group number (see manual for description)
GROUP=1
# days to keep messages before deletion
DAYS=7
# tagline ID:
# 0 - don't use taglines
# non-zero - use a tagline of the numbered group
TAGLINE=1
# date of last update (don't change)
DATE=0
# email address of the moderator of this section (if any)
MODERATOR=



$BBSDIR/msql/bin/msql Rocat <<EOF

create table $1 (
                message_number  int not null primary key,
                from_           char(50),
                to              char(50),
                subject         char(70),
                date            int,
                text            char($textsize),
                link_number     int,
                link_table      char(50),
                thread_number   int,
                local_origin    int
)
\g

create table $1_thread (
                subject         char(70) not null primary 
key,
                section         char(50),
                thread_number   int,
                messages        int
)
\g


insert into info values ('$1',
                $HIGH_MESSAGE,
                $HIGH_THREAD,
                $NUM_MESSAGES,
                $SECTION_TYPE,
                $ACL,
                $FLAGS,
                $FAMOD,
                $READ_ONLY,
                $ANONYMOUS,
                $GROUP,
                $DAYS,
                $2,
                $TAGLINE,
                $DATE,
                '$MODERATOR',
                '$3'
)\g


     First, let me go through the three options available on 
the command line:
     
Option              Description
section_name   A short (less than 50 characters) name for 
               the database.  This will not be seen by the 
               users, but will be used internally by the BBS 
               to name the table.
max_lines_per_message    The maximum number of lines per 
               message.  Note that this is a character limit 
               rather than a line limit.  A line is 80 
               characters by default.   So, the result means 
               that the message can be 
               80*max_lines_per_message characters long, 
               regardless of the real number of lines in the 
               message.  Note that each message is at least 
               this long.  So, if a user types a single word 
               message, the message within the database will 
               be this size.  Due to this, you should be a 
               bit conservative about max_lines_per_message.   
               I keep mine at 60 lines per message by 
               default.
"Long section Name" The name of the section that the users 
               see.

     I'll go through an example later.

     The options available within the script:
Option              Description
HIGH_MESSAGE   The starting message number.  Leave it at 1.
HIGH_THREAD         The starting thread number.  Leave it at 
               1.
NUM_MESSAGES   Leave at 0.
SECTION_TYPE   The section type of the message section:
                    0 - Private mesasge area
                    1 - Public (rocat) message area
                    2 - Fido message area (not used at this 
               time)
                    3 - Usenet News area (not used at this 
               time)
ACL            The access level for the area (dependant on 
               FAMOD)
FLAGS          The flags necessary for the area.
FAMOD          How ACL and FLAGS are used: (in hex)
                    0x00 - no modifiers
                    0x01 User ACL must be greater than ACL 
               to access.
                    0x02 User ACL must be equal to ACL to 
               access.
                    0x04 User ACL must be less than ACL to 
               access.
                    0x0100    User FLAGS must match FLAGS to 
               access.
                    0x0200    User FLAGS must not match 
               FLAGS to access.
               Note that the resulting number must be 
               converted to decimal for the database to 
               recognize it.
READ_ONLY      0 for read/write, 1 for read only. (only 
               SysOp and moderator can post to read_only)
ANONYMOUS      1 for anonymous posting allowed
GROUP          The read grouping.  The read grouping allows 
               the SysOp to group sections together to allow 
               user to execute a single group read of an 
               entire group of sections without having to 
               group them together themselves.  This would 
               be useful in, for example, a teen area that 
               has a number of sections available.  The 
               SysOp would then group them together using a 
               single number, then use command 48 to read 
               any messages in all of the groups.
DAYS           How many days until a message is deleted. I 
               keep it at 7 days, which means delete 
               messages 7 days after they were posted.
TAGLINE        The tagline grouping.  0 for no tagline used.  
               See the section on taglines for more 
               information.
DATE           Leave at 0.
MODERATOR      The email address of the moderator. 

     To change any of the above, simply edit the 
create_table script and change the option.  At that point, 
you may execute the script with (for example):
     create_table  Rocat 60 "Rocat Development Discussion"

     The above creates a new section called 'rocat', that 
the users will see as "Rocat Development Discussion", with a 
maximum of 4800 bytes per message.


   Taglines
     Taglines are small messages appended by the BBS 
software when a message has been posted.  Generally, they 
take the form of:
     Source: My BBS fido XX:YY/ZZZ 
     Or something similar.  Many BBSs use taglines to 
uniquely advertise both that the message came from their 
BBS, but some other item about their BBS that isn't obvious 
(like lots of files, a funny quote, etc).  
     Rocat will automatically add a tagline to those 
sections that you designate for taglines.  In addition, it 
can allow you to group taglines by subject so that 
appropriate taglines remain in appropriate groups (e.g. a 
Linux tagline doesn't belong in a Windows oriented area).  
     To configure taglines, identify which sections of the 
message base you want to group together.  This could be a 
multitude of groups, or a single group for all of the 
message base.  
     Give each group a  single number, starting at 1.  When 
creating message bases, set the TAGLINE variable shown above 
to the number.  This will group the taglines to those users.
     At this point, you'll want to add your taglines to the 
database.  A default taglines file (/bbs/text/taglines) 
comes with the BBS.  It's very short, but is very 
descriptive.  The format is:
     tag  message (up to 320 characters)
     Where tag is the number and the message is, um, the 
message.  Make sure that the message is all on one line.  If 
the message takes multiple lines, it will break the import 
script (at this point).  
     Edit this file as you want.  When you're finished, run 
/bbs/script/import_taglines.  Note that this will overwrite 
the existing taglines in the BBS database with those in the 
tagfile.


   Electronic Mail
     Rocat supports both public and private messages bases.  
The previous section detailed how the public message bases 
are configured.  Private message bases are for sending 
private messages between uses, in effect, electonic mail.  
Rocat comes with one private mail section configured.  
     Electronic mail differs from public message bases by 
where the message can come from, and, where the messages can 
go.  Public messages rarely leave the system they're on 
(excepting Usenet and FIDO, of course).  Private mail, 
however, can go to another person within the BBS, or, could 
potentially go across the world!  Due to this, the Rocat 
private message base handles email very differently than 
public messages.
     Based on the parameter MAIL_FORWARD found in the 
bbsinfo, new users, when creating their information, will 
have their mail imported into the BBS. This allows new users 
to access their mail inside the BBS.  It also allows more 
security, as the user never needs to leave the BBS to read 
mail.
     Mail forwarding into the BBS works like this:
     1.  A new message is received by the system for the 
user.
     2.  If a .forward file is found in the user's 
directory, it is used to forward the mail to the BBS. 
     3.  A front end to the msgutil program is then invoked 
to import the mail into the BBS's database.
     4.  The message is then imported into the database.  
     When the user logs on, or after some period of time if 
they're already online, the BBS will notify the user that 
new mail has arrived.  
     Mail forwarding outside the BBS works like this:
     1.  The user sends an email message to another user.
     2.  The BBS then forwards the message to the system's 
mailer for processing.  The BBS doesn't try to delver mail 
directly -- after all, some users may have mail addresses 
that go somewhere entirely different than the BBS machine.
     3.  Should the mail be for a person in the BBS, see, 
the previous description.

     It's actually pretty simple.


   Message Area Moderation and Public Message Import
     The BBS imports email as documented above.  However, 
due to the flexibility shown above, the BBS can also import 
public messages into message sections.  This was created 
with a message base moderator in mind.  A moderator is 
someone that receives all of the articles destined for a 
message section.  The moderador approves the messages if she 
determines that they're on-subject, worthwhile, etc.  
     To import a private message into the BBS, simply add 
the following line within the message:

     rocat-section: sectionname
     Note that sectionname refers to the short section name.   
The above, if found, will cause the BBS to try to import the 
message into the message area listed.  Note that security 
for the above is attempted, but can't ben entirely enforced.  
In particular, the SysOp or a moderator can be checked, 
however, more esoteric security (like the ACL and the flags) 
cannot.  Give out knowledge of the above with caution.
     To allow the above to work properly, the message being 
imported must be sent into the BBS.  This means that the 
moderator must have some place to send the email that 
results in the BBS handling the mail.  It could be the 
moderator themselves, or, it could be another user, or, even 
a dummy, import user.
     I'd recommend the import user if you're going to use 
this feature frequently.  To create an import user, make 
sure that the FORWARD_MAIL option is turned on in the 
bbsinfo, and log into the BBS as 'import'.  Once that user 
has been created, all mail to them will be imported into the 
BBS, resulting in the rocat-section keyword being searched 
for within messages.


   Message Area Maintenance
     Message areas require some maintenance.  In particular, 
the BBS must do two things nightly to the database:
Delete messages that have expired.
Update the threads tables to accurately reflect deleted 
messages.

     Fortunately, the BBS comes with a utility to do this 
for you.  Add the following to the 'bbs' user's crontab:

#
# delete expired messages
1 1 * * *       BBSDIR=/bbs;export BBSDIR; /bbs/bin/msgutil 
-e

     The msgutil utility will automatically delete expired 
messages from the database, and, update the threads for all 
areas.


   Security
     Prior to detailing how to add external programs to your 
system, I want to talk about how security works within the 
BBS itself.

   How the BBS uses Unix security
     The BBS works with the Unix security system so that 
unusual protection methods are not necessary.  Basically, 
the BBS allows users to access and change BBS files via 
running set-group-id (SGID) 'bbs'.  All files that can be 
modified by users within the BBS must be owned by group BBS, 
and writable by group BBS.  Directories must have the group 
write and group execute permissions for user access.  The 
directory structure and permissions follow:

The BBS root directory:

drwxrwx---   7 bbs      bbs          1024 May 22 22:17 admin
drwxr-x---   2 bbs      bbs          1024 Jun 28 02:01 
backup/
-rwxr-xr-x   1 bbs      bbs          516 May 16 20:32 bbs
drwxr-xr-x   2 bbs      bbs          1024 May 22 22:01 bin
drwxr-xr-x   2 bbs      bbs          1024 May 25 17:21 
config
drwxrwxr-x   2 bbs      bbs          2048 May 22 22:10 
filehdr
drwxr-xr-x   8 bbs      bbs          1024 Apr 17 11:54 files
drwxr-xr-x   3 bbs      bbs          2048 May 17 21:01 menus
drwxr-xr-x   2 bbs      bbs          1024 Feb 23 17:40 new
-rwxr-sr-x   1 bbs      bbs        259076 May 22 21:32 Rocat
drwxr-xr-x   2 bbs      bbs          1024 May 21 22:04 
scripts
drwxr-xr-x  17 bbs      bbs          1024 May 15 20:00 spool
drwxr-xr-x   2 bbs      bbs          1024 Apr 20 22:10 text
drwxrwxrwt   3 bbs      bbs          1024 May 20 01:08 tmp
drwxrwxrwt   2 bbs      bbs          1024 May 22 22:07 
uploads
drwxr-xr-x  28 bbs      bbs          1024 Feb 24 20:09 users

     Note that Rocat (the BBS program itself) is SGID.  
Everything else that needs to be writable (filehdr for files 
headers, and uploads for new uploads) are writable by the 
BBS group.  Nothing else should be writable by the BBS 
group, nor should it require BBS write access.
     Note that the admin directory permissions are 770.  If 
your admin directory doesn't have exactly the same 
permissions as above, your BBS will not work.  This is a 
common problem: BBS users can log in, but they must enter 
their information every time.  This refers to the 
permissions of the Rocat program and/or the admin directory.

     Note: Check the above very carefully.  Your permissions 
should match exactly.  Most of the problems I've seen in 
failed installations was due to the above permissions being 
incorrect.

   Security Holes - external programs
     I can't stress this enough:  WATCH OUT FOR EXTERNAL 
PROGRAMS.  This is how many crackers gain unauthorized 
access to your system.  In the directory /bbs/src/utilities 
can be found notes on how to modify some common programs to 
close some security holes.

   Interfacing with External Programs
     If you still wish to use external programs in your BBS, 
the below details how to go about adding them.
     Interfacing with external programs is simple.  When a 
user selects an external program, that program is called 
from within the BBS.  To him, it appears like the program is 
built into the BBS.  See command (21) above for more 
information.
     WARNING:  External programs that are not compiled with 
security turned on are huge security holes.  An example that 
I found recently:
     I use the 'tin' news reader.  As part of tin, it's 
possible to do a shell command (via the '!' character).  If 
you compile tin to turn this off (which you should), then 
you will not have problems.  However, I was able to type 
'chsh -s /bin/tcsh', and the shell command changed my shell 
from the BBS to a shell account.  It was this simple.
     Solution (in this case):  I turned off 'chsh'.  I've 
also tried to minimize problems through the use of a 
restricted BASH shell.  The BBS currently uses the -r 
(restricted) option on BASH to gain a small amount of 
security  (it doesn't buy much)
     WARNING:  When you put an external command in your BBS, 
you must test this command for shell-giving options.  If you 
do not, you are opening your system to crackers; people who 
break systems for the fun of it.  
     In other words:  
     If you are not sure of the security of a program, do 
not add it to your BBS. 
 
     You will save yourself hours of work restoring your BBS 
if you avoid externals as much as possible.

   Using a restricted shell
     In rocat-0.86, I added a '-r' flag to the part that 
starts external programs.  This invoked the 'restricted' 
part of BASH.  However, I've found that BASH doesn't come 
with the restricted feature compiled in, by default.  So, 
I've added another define for restricted BASH in 
/bbs/src/bbs.h:
     #undef HAVE_RESTRICTED_BASH
     If you have a BASH that works with the '-r' option, 
change this to a 'define' to give yourself a small amount of 
security.

   BBS Maintenance

   Backing up your BBS
     Back up your BBS immediately!  Before you do anything 
more to your BBS, you should have a working copy on tape (or 
floppy, as necessary).  

     At this time, I'm a bit lax in my backups.  However, 
here is my current schedule:
     
     Contents                 When
     Critical (changable) files         Weekly
     Non-critical files (downloads, etc)     Monthly

     Invest in a good tape drive large enough to back up 
your system in one, or potentially two, tapes.  Good quality 
DAT drives have come down in price in the last year.  Get 
one.  Being able to back up your system unattended will save 
you many hours of wasted time switching tapes (or floppies).  
In addition, the publically available backup software for 
Linux has gotten incredibly good over the last year.  
     A BBS that is not regularly backed up is a BBS about to 
fail!

   Database Backups
     Database corruption happens.  It has yet to happen to 
me, but I don't promise it will not happen.  I've tried to 
make the BBS as bulletproof as possible, but I can't 
envision every possible configuration for the Rocat system.  
Due to this, you want to backup your database regularly.   
     The BBS comes with a script to extract the data from 
the database.  Put the following entry into the 'bbs' user's 
crontab:

#
# backup the database nightly
1 2 * * *       BBSDIR=/bbs;export BBSDIR; 
/bbs/scripts/nightly_db_backup

     The above script will create a nightly backup file for 
your message base in /bbs/backup/rocat.NN, where NN is the 
day of the month for the backup.  This will automatically 
save up to 31 database backups in the directory with no 
intervention.  In addition, no deletion of the files is 
necessary as the backup done on any particular day of the 
month will take the place of the previous month's backup for 
that day.  
     Of course, should your database get huge, you'll want 
to put the backups somewhere with enough space to handle 
them.  One other thing to consider is the whether to put the 
backups on the same physical disk as the BBS -- after all, 
if your BBS disk crashes, having the database backups on the 
same disk won't help much!  If you can possibly afford it, 
I'd mount a small disk as /bbs/backup.  This will allow 
backups to be fast (disk to disk rather than on the same 
disk) as well as reliable (if the BBS disk crashes, you have 
your database disk for the restore).
     To recover a backup, follow the following instructions:

1.  Delete the current database (it's corrupted after all):
     msqladmin delete Rocat
2.  Recreate the database (an empty one at this point):
     msqladmin create Rocat
3.  Now add the data from the backup.  Note that this could 
take a long time if your database was very large.
     msql < backup_database_file



   SysOp Utilities
     There are a number of utilities I've written to make 
the BBS easier to maintain.  They are:

     Program        Description
     fileutil       a utility for maintaining files areas
     errlogd        the BBS error logger
     msgutil        message utilities

     Let's begin with fileutil.  I wrote fileutil to give me 
more information about my files areas without having to look 
at the files areas manually.  The options available are c, 
n, m, u and d.  They are:

     Option         Description
     c         create files areas.  For INITIAL SETUP ONLY.  
               This option will scan the directories that 
               are supposed to have files in them, and 
               automatically add those files to the files 
               area automatically (with blank descriptions).  
               This requires a files area name (just to make 
               sure you want to do this)
               Note:  I do not recommend this option any 
               longer.  The functionality of this can be 
               accomplished with the 'new' files without the 
               danger of overwriting your existing 
               descriptions.  It will probably go away in 
               the future!
     n         List the new files in all files sections to a 
               file.  Requires a filename to save the list 
               to.
     m         List the most popular files on the BBS.  
               Requires a filename to save the list to.
     u         Update all files areas for new files and 
               delete those files with zero length in their 
               descriptions.
     d         Delete files that exist in the headers but do 
               not exist in the files directory.  You will 
               want to do this occasionally to clean out 
               failed uploads and files you may have 
               deleted.  Note:  You want to clean up the 
               uploads area prior to executing this command.  
               If  you do not put the files found in the 
               upload area in the files directory, the 
               description for the file will be deleted.

     Here is a sample output from a typical new files 
listing:

New files in the last 7 days.  (05/25/94)
Name           Section                     Date   by    
Downloads
cyclone1.cpt   Macintosh Games           05/20/94 sruby     
0
cyclone2.cpt   Macintosh Games           05/20/94 sruby     
0
modvoicer1.1.c Macintosh Sounds          05/22/94 sruby     
0
mono2stereo.cp Macintosh Sounds          05/22/94 sruby     
0
2WayTalker2.1. Macintosh Sounds          05/22/94 sruby     
0
99bottlesofbee Macintosh Sounds          05/22/94 sruby     
0
note           Macintosh Utilities       05/20/94 sruby     
0
eyeballs.sea   Macintosh Utilities       05/20/94 sruby     
0
numbercrunch.s Macintosh Utilities       05/20/94 sruby     
0
todo3.03.sit   Macintosh Utilities       05/20/94 sruby     
0
windows3.0.cpt Macintosh Utilities       05/20/94 sruby     
0
poor-mans-newt Macintosh Utilities       05/20/94 sruby     
0
chemcalc.sit   Macintosh Utilities       05/20/94 sruby     
0
clik'x.sit     Macintosh Utilities       05/20/94 sruby     
0
periodictable. Macintosh Utilities       05/20/94 sruby     
0
intrslip.sea   Macintosh Utilities       05/20/94 sysop     
0

     The 'most popular' listing is similar.

     Typically, you'll run 'new' files, 'most popular' files 
and 'update' files options nightly via cron.  Here is the 
crontab I use on the BBS to generate the reports 
automatically to system text files:

# bbs crontab -- automatic bbs maintenance
#
# update file sections for new files
0 3 * * *       setenv BBSDIR /bbs; /bbs/bin/fileutil -u
#
# update new files listing
1 3 * * *       setenv BBSDIR /bbs; /bbs/bin/fileutil -n 
/bbs/text/system2.msg
#
# update most popular files listing
2 3 * * *       setenv BBSDIR /bbs; /bbs/bin/fileutil -m 
/bbs/text/system3.msg

     Note how the BBSDIR environment variable is set prior 
to executing the command.  Mail is sent nightly to 'bbs' for 
the first command, and the output for the next two commands 
go to system2.msg and system3.msg so that users see the new 
files and most popular files upon logon.

     The next utility is the error logging utility, errlogd.  
Errlogd accepts error (and status) messages from parts of 
the BBS and logs them to the central log file, 
/bbs/admin/bbserr.  A typical bbserr log looks like:

06/29/96 23:14:25: (manwe S8) Logon for Rod Green from 
Highlands,CO
06/29/96 23:14:30: (manwe S8) called fortune
06/29/96 23:14:36: (manwe S8) menu: files/top_linux
06/29/96 23:14:38: (manwe S8) menu: files/linux/top_sources
06/29/96 23:14:42: (manwe S8) menu: files/linux/sources/news
06/29/96 23:14:54: (manwe S8) menu: files/linux/top_binaries
06/29/96 23:14:57: (manwe S8) menu: 
files/linux/binaries/games
06/29/96 23:15:08: (manwe S8) menu: files/linux/top_sources
06/29/96 23:15:11: (manwe S8) menu: files/linux/sources/html
06/29/96 23:15:17: (manwe S8) menu: files/linux/sources/bbs
06/29/96 23:15:24: (manwe S8) called sz rocat-1.03.tar.gz
06/29/96 23:22:12: (manwe S8) rgreen downloaded 
rocat-1.03.tar.gz
06/29/96 23:22:22: (manwe S8) menu: 
files/linux/sources/database
06/29/96 23:22:27: (manwe S8) menu: 
files/linux/sources/development
06/29/96 23:22:40: (manwe S8) Logoff for Rod Green

Note how the BBS has logged everything (more or less) that 
the user did in their session.  This gives you not only 
information about what the users were doing on your BBS, 
but, where the user was located within the BBS at the time 
of an error.  This can be very helpful when tracking down 
menu problems.

     Check your error logs frequently; many times, it will 
be the only indicator of a problem within your BBS.

     The last utility is the messages utility, msgutil.  
Msgutil has only two functions at this time:

1  Importing email into the BBS.
2  Expiring messages within the BBS.

     Both functions are very important.  See the messages 
section for details about import/export of messages and 
message expiration.

   Trimming Log Files
     Over time, log files grow to unmanageable levels.  
You'll want to look at the following files and periodically 
move them to another filename and gzip them.  After you're 
sure you don't need the files, delete them.
     Filename
     /bbs/admin/bbserr

     See the next section for deleting inactive users from 
the userlog and the passwd file.


   User Maintenance
     Editing of users is now part of the BBS system itself.  
Please refer to the example SysOp menu found in the 
examples/menus directory.  The menu commands you should look 
at closely are commands 40-43.

40        Search for users to edit/delete
41        Delete inactive users
42        List inactive users
43        List users for edit/delete

     New to version 1.0 is the automatic editing update of 
online users.  Should you want to edit a user online, simply 
edit them as you normally would.  Once you are done, a file 
is written to tell the BBS that the user's information has 
changed and to update their information immediately.
     The above commands will allow you to delete users from 
your BBS.  Howerver, they will not delete users from the 
/etc/password.  To do this would require the BBS system to 
run as root (or have some piece that runs as root), which 
would be an immense security hole.  The BBS comes with a 
script in /bbs/scripts/checkpw.pl that will check the 
password and shadow files against the userlog, deleting the 
users of the BBS that are no longer in the userlog.  In 
other words:
     1.  As the BBS Administrator, run a command 43 from the 
sysop menu.
     2.   Get out of the BBS.
     3.  'su' to root.
          su
          <enter root password>
     4.  cd to tmp
          cd /tmp
     5.  Run the script.
          /bbs/scripts/checkpw.pl
     6.  Save your old passwd and shadow.
          mv /etc/passwd /etc/passwd.old
          mv /etc/shadow /etc/shadow.old
     7.  Move your new passwd and shadow to /etc
          mv ./passwd.new /etc/passwd
          mv ./shadow.new /etc/shadow
     8.  Change the permissions back.
          chown root /etc/passwd
          chown root.bin /etc/shadow
          chmod 644 /etc/passwd
          chmod 640 /etc/shadow


   Troubleshooting

   Watching the Logs
     The Rocat BBS system logs all messages and errors, if 
at all possible.  However, to do this you must turn on the 
error logging daemon.  This is done by logging in as the BBS 
Administrator, and typing the following command: (from 
above)
     /bbs/bin/errlogd &
     The above command will start the error logging daemon 
and push it into the background.  The daemon will run in the 
background, waiting for messages from BBS programs about 
errors or status messages.
     The file that is used for error logging is 
/bbs/admin/bbserr.  You'll want to check this file 
frequently in the first months of running the BBS.  This 
file will tell you if you've got problems with menus, files 
areas, etc.  It will also tell you who's logged in, and what 
they did (within reason).  A sample output would be:

05/20/94 10:58:30: (S8) Logon for Alpha Tester
05/20/94 10:58:54: (S8) Got signal 1
05/20/94 10:58:55: (S8) (hangup) Logoff for Alpha Tester
05/20/94 12:54:19: (S8) Logon for Bill Clinton
05/20/94 12:55:03: (S8) Bad line A in files area macapps
05/20/94 12:55:03: (S8) Filename was bbedit
05/20/94 12:56:51: (S8) Logoff for Bill Clinton
05/20/94 21:47:20: (S9) Logon for Alpha Tester
05/20/94 21:47:45: (S9) Got signal 1
05/20/94 21:47:45: (S9) (hangup) Logoff for Alpha Tester
05/20/94 21:48:51: (S9) Logon for Alpha Tester
05/20/94 21:49:06: (S9) Got signal 1
05/20/94 21:49:06: (S9) (hangup) Logoff for Alpha Tester

     The above list shows what goes on in the BBS.  In the 
first few lines, you see Alpha Tester log onto the BBS on 
tty line ttyS8.  (it was really me doing some testing).  The 
BBS got signal 1 (a hangup, caused by turning off the 
modem), which caused the BBS to log the user off.  Note that 
the BBS will always update it's information, if possible, 
upon logout of a user.  (e.g. if the user decides to be 
tricky and download a bunch of files, and drop carrier in 
hopes of getting his time over again, it won't work)
     Note that a hangup is not a graceful way to exit the 
BBS.  You really don't want people doing this on a regular 
basis.  It breeds a sense of irresponsibility in users, and 
tends to irritate SysOps.
     Note 2:  The (S8) in the above example is will show up 
differently on a multiple machine BBS.  See the section on 
multiple machine BBSs for more information.

   Watching for Problems
     Eventually, your BBS will break.  This can be due to 
many factors, including hardware, weather, irate or 
destructive users, errant programs, etc.
     Over time, I've found a few items that I check 
regularly:
Item           Description
Modem Capability    If your BBS goes from busy to no 
               callers, check that your modem is working.  
               If the users can't connect, they cannot tell 
               you of the problem.
Login Capability    Can you log in as a test user?  Are 
               things working correctly?
Chat Capability     Has the chat server(s) gone out to 
               lunch?  Use the status commands found in the 
               sysop menu to check the server status.
Email Capability    Is mail working?  Send a couple of test 
               messages to make sure.
Machine Running?    Is everything working on the machine?  
               Can you execute common commands? 
     
     I've found that most errors can be found by routine 
testing.  Many times, your users will be unable to report 
problems to you directly.  In that case, you must know of 
the problem yourself to fix it.

   Check your Security
     Most potential problems can be attributed to 
permissions problems.  See the directory listing of the /bbs 
directory in the Security section.   

   Additional Information

   Accessing the BBS from the Shell
     Generally, a user will log into the system and use it 
normally without problems.  However, there exceptions.  When 
a user has a shell account, and wishes to access the BBS, 
how does he do that?  How does he upload without uploading 
through the BBS itself?
     The answer to these questions is to mimic how the BBS 
works normally.
     For a user to log into the BBS from a shell account, he 
can type 
     /bbs/bbs
     And he will see the BBS just like everybody that has 
/bbs/bbs as their login shell.
     Similarly, uploading to the BBS via the command line is 
accomplished by doing what the BBS does normally.  When a 
user uploads via the command line, he should do the 
following:
     1.  Upload the files as he normally would via the 
command line.
          rz
     2.  Make a directory in /bbs/tmp with his login name as 
the name.
          mkdir /bbs/tmp/myloginname
     3.  Copy the files that are for a particular files 
section to that directory.
          cp * /bbs/tmp/myloginname
     4.  Enter the BBS.
          /bbs/bbs
     5.  Go to the files area where the files are to be put.
     6.  Select 'upload'.  
     7.  Select zmodem as the protocol.
     8.  Type ctrl-x a number of times.  This will abort the 
upload.
     9.  The BBS will ask 'Was the upload successful?'.  
Type 'y'.
     10.  The BBS will then prompt you for descriptions for 
all files found in the 
     /bbs/tmp/myloginname directory.

   File Formats
     All files found within Rocat,with the exeption of the 
datbase files, are completely editable text.  This allows 
you (the SysOp) to go into the file and look for (and 
hopefully fix) problems.   You will have corruption happen 
eventually (due to a crash, invalid input, whatever).  
Whether it is a bad disk block, a panic of the system or 
even just a user with a weird combination of letters, you 
will see something wrong eventually.

   The Userlog
     There are three files that haven't been described yet, 
the userlog, a files header (there are many files headers in 
a typical BBS installation) and the door.sys file.  Let's 
start with the userlog.
     For every user in the BBS, there is a userlog record.  
The record is comprised of 4 lines of data, space separated.  
A typical line follows:

[A shaw Greg Shaw shaw CO Westminster ]
[B vt100 769579635 1 0 0 blue 0 0 769579635 ]
[C 0 0 0 1 vi 24 80 english ]
[D 0 200 40 8 769579635 0 76979635 3 1 ]

     In the above, you see my entry.  As you can see, there 
is a lot of information in the entry, and it's not obvious 
about what a lot of those 0's and numbers mean.
     Before I jump in, I've labeled each line uniquely with 
A through D.  Also, every line is within square brackets.  I 
didn't add this when I put it into this document.  This 
format is required for the BBS.  This allows the BBS to 
check for errors in the Userlog file.  Every record should 
have an A through D record.  If that format is broken, an 
error message will be sent to the error logger, and the BBS 
will exit (to make sure that damage isn't propagated).
     The line formats are:
[A login_name first_name last_name alias state city]
[B terminal_type last_logon_time #_of_logons downloads 
uploads card_color total_kused total_timeused validation]
[C #_of_private_messages #_of_public_messages credited_time 
has_color editor lines columns]
[D flags access_level timelimit timeused_last_call 
anniversary_date K_downloaded_last_call expiration_time 
chat_foreground chat_background ]

     The fields are (in order of ocurrence):
Field          Description
(line A)
login_name     The name used to logon to the system (from 
the passwd file)
first name     The user's first name
last name The user's last name
alias          The user's alias (to be used for chatting)
state          The state the user calls from
city      The city the user calls from
(line B)
terminal_type  The terminal type that the user's software 
supports
last_logon     Unix time format (seconds) for when the user 
last logged on
#_logons  The number of times the user has logged into the 
system
downloads The number of downloads by the user
uploads        The number of uploads by the user
card_color     The access card color of the user
total_kused    The total amount of K downloaded by the user 
(1.0)
total_timeused The total amount of time used by the user 
(1.0)
validation     The date when the user was validated (1.0)
(line C)
#_private The number of private messages the user has 
entered (not used)
#_public  The number of public messages the user has entered 
(not used)
credited_time  The number of minutes of credited time the 
user has available
has_color Does the user have color? (0 for no, 1 for yes)
editor         The name of the user's favorite text editor
lines          The number of lines on the user's display
columns   The number of columns on the user's display
language  The language selected by the user (or the BBS) 
(0.86)
(line D)
flags          The user's access flags (in hex)
access_level   The user's access level
timelimit The number of minutes the user gets per logon
timeused_last_call  The number of minutes the user used last 
call
anniversary_date    The date of the first logon by the user
K_downloaded   The amount of 1024 byte blocks the user 
downloaded last call
expiration_time     The time the user last logged in within 
the timeout period
chat_foreground     The color chosen by the user for the 
display of their chat.  
chat_background     The background color chosen by the user 
for display of their chat.

     Some notes:
        The city field can be multiple words
        The login name can be only two words.  The BBS warns 
             users not to enter more than two words, or 
             enter an underscore between the last two words.
        timeused_last_call is cumulative over the time 
             period defined by WAITTIME in the config file.  
             If the user logs in for 5 minutes at the top of 
             each hour for four hours, the 
             timeused_last_call will be 20.  This is to make 
             sure that users don't get more time than 
             they're supposed to get.
        The credited time field is also cumulative over the 
             WAITTIME period.  After 12 hours, that time is 
             discarded.
        Access level, card color and flags are independent 
             of one another.  (see above sections for 
             description)
        The language will be entered into the userlog field 
             regardless of whether the BBS uses multiple 
             languages.
        The expiration time is new to 0.90.  This is the 
             time that the user last logged in, if within 
             the timeout period set in /bbs/config/bbsinfo 
             file.  If the user hasn't logged in within that 
             time, the user time is reset to their default.


   Files Sections
     The other file format that hasn't been described is the 
files header file.  A typical line from that file would be:

[A shaw 1 pb10.zoo]
[B A GIF/JPEG viewer for VESA systems. ]
[C DOS, VESA compatible driver ]
[D This is a GIF/JPEG viewer for DOS.  It uses VESA 
compatible modes, so if you]
[E have a VESA compatible driver, get this program. ]
[F  ]

     The files header information is comprised of 6 lines, 
of the same format as the Userlog information (square 
brackets and A-F labels).  The contents of a record:

[A uploader number_of_downloads filename]
[B short description ]
[C hardware/software requirements]
[D line 1 of long description]
[E line 2 of long description]
[F line 3 of long description]

     Most of the above is self explanatory.  A few notes:
            The filename must not have spaces in it at this 
point.  I will be fixing this in the next release.  I will 
be adding quotes around the filename.
            The short description should be less than 40 
characters (so that it will fit on the screen)
            All fields from B onward are optional.  Nothing 
will be printed if the field is empty.

   Editors Format
     The editors file (/bbs/config/editors) format is very 
similar to that found within the protocols file.  In 
previous releases, the editors file was a text file shown to 
the user.  This was a very large security hole.  At this 
point, the editor must be chosen from the editors file, 
limiting those editors available to the user.
     The editors file has the following format:

editor_command|key_to_select|text_describing_editor

An example would be:

vi|1|1.  The 'vi' editor.  Very cool, but difficult to 
learn.

Any # found in the file will be cause the rest of the line 
to be ignored.

   DOOR.SYS Format
     The DOOR.SYS format for spawning BBS externals has been 
established for a number of years.  I've included with the 
BBS a copy of the original document.  It may be found in 
/bbs/doc/doorsys.txt.  Rather than quote that document here, 
let me go through the pieces that Rocat expects.  Note:  I 
don't expect anybody that isn't a programmer to use the 
following information.  
     At this time, the door information is not written to a 
door.sys file.  Rather, the file is written to 
/bbs/spool/door/username.doorsys, where username is the 
login name of the user to whom the file belongs.
     For any future externals, I'd like all potential 
authors use this file rather than try to decipher the 
userlog (and any other pieces), as the format of the BBS 
files may change at any time.  The door.sys file format is a 
standard, and should remain static.

// Structure:  DoorSys
// Purpose:    store the door switch file format as per the 
DOORSYS.TXT
//        standard
// Author:     Gregory Shaw
// Created:    6/14/95
// Notes: Those pieces of this file that don't apply will 
have a
//        value that makes sense in the context of that 
variable.
//        Those that are not used actively (e.g. have a 
dummy value)
//        have (dv) in the comment
//        There are a number of items unique to this BBS 
that don't 
//        make sense in a msdos environment.  Their mapping 
is:
//             Value               Stored within
//             -----               -------------
//             terminal type       work phone
//             language       password
//             card color          comment (field 1)
//             editor              comment (field 2)
//        The attempt has been made to make sure that any 
externals
//        used by PC-BBS systems can work with this file.

typedef struct 
{
     char comport[10];   // communications port (COM0: = 
local) (dv)
     int  baud;          // baud rate (dv)
     int  parity;        // parity (dv)
     int  node;          // node number
     int  DTErate;  // DTE rate (Actual BPS rate) (dv)
     char screen;        // screen display (Y = on, N = off) 
(dv)
     char printer;  // printer display (Y = on, N = off) 
(dv)
     char pagebell; // use bell for page (Y = on, N = off) 
(dv)
     char calleralarm;   // caller alarm (Y = on, N = off) 
(dv)
     char fullname[50];  // user's full name
     char callfrom[50];  // calling from location
     char homephone[20]; // home phone number (dv)
     char workphone[20]; // work/data phone number (terminal 
type)
     char password[20];  // password (language)
     int  seclevel; // security level
     int  timeson;  // total times on
     char lastcall[10];  // date last call (mm/dd/yy)
     long secsremaining; // seconds remaining this call
     int  minsremaining; // minutes remaining this call
     char graphicmode[4];// Graphics mode (GR=graph, 
NG=nongraph)
     int  pagelength;    // page length
     char usermode; // user mode (Y = expert, N = novice) 
(dv)
     char confs[100];    // conferences registered in (7 
max, comma
                    // separated list of numbers 1-7) (dv)
     int  confexit; // conference exited to door from 
(single number)      (dv)
     char expdate[10];   // user expiration date (mm/dd/yy)
     int  recnum;        // record number in userlog file 
(dv)
     char defprotocol;   // default protocol (X,C,Y,G,I,N,Z, 
etc.) (dv)
     int  uploads;  // total number of uploads 
     int  downloads;     // total number of downloads
     int  daily_k;  // daily download 'K' total 
     int  daily_k_max;   // daily download 'K' max
     char birth[10];     // caller's birthdate (mm/dd/yy) 
(dv)
     char      mainpath[100]; // path to MAIN directory 
(where userlog resides)
     char genpath[100];  // path to GEN (?) directory (dv)
     char sysopname[MAX_LOGIN_LENGTH];  // sysop's login 
name
     char aliasname[MAX_ALIAS_LENGTH];  // alias name
     char eventtime[10]; // event time (netmail processing) 
(hh:mm) (dv)
     char ecc;      // error correcting connection? (Y/N) 
(dv)
     char ansi;          // ANSI supported & caller using NG 
mode? (Y/N)
     char recordlock;    // use record locking? (Y/N) (dv)
     char defaultcolor;  // BBS default color (1-15) 
     int  credit;        // time credits in minutes
     char newfiles[10];  // last new files scan date 
(mm/dd/yy)
     char calltime[10];  // time of this call (hh:mm)
     char lastcalltime[10];   // time of last call (hh:mm)
     int  maxfilesday;   // maximum # daily files available 
for download (dv)
     int  filestoday;    // # of files downloaded today
     int  upload_k; // total 'K' bytes uploaded (dv)
     int  download_k;    // total 'K' bytes downloaded (dv)
     char comment[100];  // user comment (color 
     int  doorsopened;   // total doors opened (dv)
     int  messagesleft;  // total messages left (dv)
} DoorSys;

     The above file is an ascii text file in the DOS style 
(CR+NL at the end of the file).  Each item is on a line by 
itself using the above format.  Should the format be 
unclear, please reference the door.sys documentation found 
in /bbs/doc/doorsys.txt.

   Linking External Programs to your BBS
     Very few BBS systems run with only the initial BBS 
software as the entire BBS system.  Eventually, you'll want 
to add something to your BBS that adds some capability not 
found within the BBS.  In this section, I go through some of 
the more obvious external subsystems you will want to add.  
Note that door.sys file usage is the only officially 
supported door mechanism.  Should a door read/write the 
userlog, it will need to be updated every time the BBS 
userlog changes.  In addition, I forsee the userlog being 
moved into the database in the next couple of versions.  

   BBS Doors
     Included with the 1.0 release of Rocat is the 
capability to call bbs externals (doors in DOS BBS speak) 
with the use of a DOS-style door.sys file.  See the previous 
section for more information about the door.sys file.


   Installing the BattleField
     To demonstrate the door capability, I've included a 
game I wrote back in 1987 (when I was writing BBS externals 
for Macintosh BBS systems) called BattleField.  To install 
BattleField, do the following:
     1.  cd to /bbs/src/bf.
          cd /bbs/src/bf
     2.   Execute a make clean.
          make clean
     3.  Execute a make.
          make
     4.  Execute a make install to install the program and 
menus.
          make install
     5.  Add a command to a menu to execute the program 
(using command  22) to your games menu.
          22|p|||||bf|   Play BattleField
     6.  Enter the BBS and enter the game.
     7.  The game will then ask you the parameters to use: 

I am unable to find an options file.

Would you like to configure The BattleField? [Y/N] Y

What is the timelimit for the players to have for one
session in BattleField? (in minutes) [20] 

How many times may the player enter the game per day? [2] 

How many days should unread (or not deleted) messages remain
prior to automatic deletion? [7] 

How many days before the game automatically resets to clear 
the board? 
(0 for no reset) [120] 

Should BattleField create a scores (rankings) file? [Y/N] y

Please enter an absolute path for the scores file: 
[/bbs/admin/bfscores] 

Difficulty: 1 - Easy 10 - Very Hard
What difficulty should this game have?  [1] 

Please enter the minimum access level for a SysOp: 

I can't find you in the playerfile. 

Would you like me to roll a character for you? [Y/N] n

     As you can see from the above, the options are pretty 
straightforward.  They are:
          Option         Description
          timelimit The amount of time the user gets in the 
game
          entries        The number of entries per day.
          mail_del       The number of days until 
public/unread mail is deleted
          reset          How many days a tournament runs 
(make big for no tournament)
          scores         The path to the scores file (plain 
text).
          difficulty     The game difficulty.  Keep it easy 
                    until people get experienced.
          access    The minimum access level for the SysOp 
                    (used so that sysop can enter without 
                    restriction)
     Notes:
          To reset the game, go into the game and inside the 
sysop menu is a reset option.
          To reconfigure the game, delete the file 
/bbs/config/bf/BattleField Options.  At that point, you can
                re-enter the game and it will ask to be 
configured once again.
          The game is pretty solid.  However, I haven't 
tested it exhaustively.  It's large and very complex.
               This makes testing rather difficult.

   Using UQWK for off-line Mail and News
     Since the 0.95 of the BBS, I've installed UQWK, a QWK 
mail processor for Unix.  Since so many people use QWK in 
accessing their BBS, I've included the 1.8 release of UQWK 
with the BBS source.  The source is found in 
$BBSDIR/src/utilities/uqwk-1.8.  Use the following to 
install:
     1.  cd to $BBSDIR/src/utilities/uqwk-1.8
          cd $BBSDIR/src/utilities/uqwk-1.8
     2.  make the program
          make
     3.  copy the program to $BBSDIR/bin
          cp uqwk $BBSDIR/bin

     There are a number of files included with the BBS that 
work to make the QWK system work.  They are:

     Script         Description
     new_zip_qwk    Builds a QWK packet with a PKZIP 2.04 
compatible compressor 
     old_zip_qwk    Builds a QWK packet in PKZIP 1.XX 
compatible formation (no compression)

     The above scripts shouldn't need to be edited.

     You should now edit the menu found in 
$BBSDIR/menus/messages/qwk.  It has some specific QWK 
options build into the menu for the building/processing of 
QWK packets.  See the man page for uqwk for more 
information.  (It's located in the source directory.  You 
may look at it by typing:  nroff -man uqwk.man | more)

   How to connect to FIDONet
     At this time, I do not have FIDONet installed on my 
BBS.  I hope to do this in the future.  If you wish to do 
this, please look at the IFMail package (or other packages) 
available on the Internet.

   UUCP, Mail and News
     UUCP is the primary transfer medium for many e-mail and 
news sites.  It is my primary medium.  Please read the Linux 
HOWTOs and the Linux FAQs for instructions for installation 
and use of UUCP/News/Mail.  These are really complex 
subjects for a complex (yet very useful) set of programs.

   Other Information

   To Do
     There are a number of things that I plan to do to 
continue developing the BBS interface.  When I initially 
designed the BBS, I wanted to have a BBS with at least the 
capabilities of current BBS systems (within reason; I don't 
consider a full graphical user interface reasonable at this 
point).  
     I'd wanted to have a fully featured monitor system 
available for release 1.0.  However, it turns out that 
something in the compilation screws up when the monitor is 
included.  Until I get this fixed, I'm working without the 
monitor.
     In the future, I hope to move both the userlog and the 
files areas into the database.  This will allow seamless 
access from other systems (without NFS mounting problems).


   Expanding your BBS

   More than two serial lines
     This BBS was meant to run with any number of 
lines/users (provided your computer can handle the load).  
However, I wanted to make sure that you understand what is 
related to using more than one serial line.
     Generally, running more than two serial lines requires 
the use of either a Unix-specific card or a 'smart' card.  
The Unix specific card is what I currently use in The Roman 
Catacombs.  I like its capabilities, and especially the 
price.  These cards run about $100.00 (US dollars).  
However, these cards can influence the load on the system 
because of the number of interrupts generated during 
high-speed file transfers.  
     This is why I recommend a 'smart' card for anything 
more than 4 lines.  Cyclades currently offers 'smart' cards 
for Linux.  I do not know if they work well, but I have 
heard good things about them.  Other vendors also have smart 
cards available for Linux (Digiboard and Stallion come to 
mind).
     I know I have glossed over the above two items, but I 
don't want to re-iterate information that is available in 
the Linux Frequently Asked Questions and the Linux HOWTOs.  
For more information, please see these documents.

   Multiple Machines and Large Setups

   Compiling the BBS for multiple machines
     The BBS currently supports the reporting of errors with 
the machine name.  However, this option is turned off by 
default.  To turn this option on, edit the file 
'/bbs/src/bbshdr.h'.  In that file, you'll find a line:
     #undef    MULTIPLE_MACHINE_BBS

     Change the undef to a define.  Recompile.  At this 
point, your error messages will look like the following:

10/17/94 02:40:21: (manwe S9) Logon for Loyd Craft
10/17/94 02:51:48: (manwe S9) Logoff for Loyd Craft
10/17/94 07:27:08: (varda p4) Logon for BBS Administrator
10/17/94 07:27:24: (varda p4) Unable to find macapps in bbs 
main files header.
10/17/94 07:27:31: (varda p4) Logoff for BBS Administrator

     The changes are reflected in the machine name being 
placed in front of the tty.  This can be helpful when you've 
got a number of machines and errors are coming from one 
machine in particular.


   Monitoring through IP sockets
     Let me explain a little bit more about how the BBS 
reports errors and does it's 'monitor' connections.  
     Currently, the BBS uses IP sockets as it's primary 
Inter-Process Communications medium (IPC).  This allows you, 
the SysOp, to monitor the system from another location on 
the network.  This is done by the changing two lines in the 
options (bbsinfo) file:
     Option         Description
     LOGHOST   the hostname of the host that is running the 
errlog daemon
     WATCHHOST the hostname of the host that is running the 
monitor daemon

     If you should have two machines, you can change the 
above options to point to your other machine, if necessary.  
I wrote it this way for two reasons:
     1.  In my opinion (IMO), any BBS machine that runs this 
program (and doesn't have tons of horsepower) will be a 
dedicated machine.   
     2.  Should you wish to run multiple BBS machines, you'd 
want all error messages to go to a single file.  I keep this 
in mind because I've seen quite a few BBSs blossom into HUGE 
network based systems.  A BBS that focuses on single-machine 
usage limits the growth of the BBS.

     Now I may be wrong about number one above, but I like 
to plan for future growth rather than limit myself to single 
machine designs.
          A few notes about running multiple machines:
      When running with multiple machines, you want your 
     most reliable system to run as the error logging system
      Should you run multiple BBS machines, running one 
     pointing to itself and the other pointing to the first 
     is the best option.
      If you have two linux boxes and want to run the BBS 
     on one and the error logging processes on the other, 
     please remember that no error logging will be done 
     should you, for instance, reboot to DOS to play a quick 
     game of DOOM.  In this case, you'll want error logging 
     to stay on the BBS machine.
      If it wasn't clear before, running the error logging 
     daemon is optional, but generally useful.  It isn't 
     necessary to run the logger, but if it is not running, 
     it won't be able to tell you should an error occur.



   Updating from a previous release

   Updating from Rocat 0.75
     There have been a number of changes since 0.75.  They 
are:
           Bug fixes (of course!)
           Support for CD-ROM filesystems
           A change in the configuration of the files 
header files to eliminate duplicated    information.
     
     See the CD-ROM section for how to setup a CD-ROM 
section.

     The files section header used to contain both the size 
of the file and the date the file was uploaded.  I did this 
so that I wouldn't have to look up the file on every access.  

     Well, it turned out that I started doing that anyway so 
that I could indicate whether the file was available.  
Combining the two operations resulted in the file 
information being read from the directory structure 'live'.  
Note that this could impact a large files section (~500 
files or larger) on a slow drive (aka CD-ROM).

     Due to the change in the files header, you *MUST* 
update your files section headers to the new format prior to 
installing the program.  I've furnished a program, 
filesupdate, that will do this for you.  Simply run the 
program for usage (and *SAVE* a copy of your old sections, 
just for security).


   Updating from Rocat 0.80
There have been a number of changes to Rocat since 0.75:
       All text that the user can see has been extracted 
from the BBS and placed into a single file in the 
/bbs/src/lang directory.  See the language section for setup 
and use.
      The BBS now operates differently when executing 
external applications.  Prior to now, when the user executed 
the external, no time checking was done.  This allowed the 
user to take as much time as (s)he wanted in the external.  
In this version, the BBS starts the external and watches the 
time.  (it sleeps for 10 seconds between waits)  When the 
user is down to 3 minutes, (s)he is warned that their time 
is about to expire and to log out.  At 1 minute, they're 
given a similar warning.  When their time is up, the 
external is killed and the BBS logs the user out.
      With regard to the above option, I've added the 
FUDGETIMELIMIT option in the bbsinfo.  This is used when the 
user has used all of their time downloading and is still in 
the process of downloading.  This option was added in hopes 
of the user overestimating their download time being able to 
finish their download.  Notes:
          1.  This is only available on download.  Other 
externals get the previous option's treatment.
          2.  The FUDGETIMLIMIT percentage is computed from 
the remaining time that the user has.  In other words, if he 
has only 5 minutes left from an hour, he only has 5% of the 
5 minutes available.  (it uses minute granularity)
      When a user marks a file and continues to view the 
downloads area, it will now place a star to mark those files 
that the user has 'marked' for download.
      There is a new option in the bbsinfo file that allows 
the sysop to turn off mail checking.  If you don't want the 
BBS to check for mail at any time, set CHECKMAIL to 0 in 
bbsinfo.
      The BBS now has a 'reset stack' menu command.  This 
works like a command 2 (change menu), but rather than push 
the menu onto the stack, this menu empties the stack.  This 
results in the new menu being the new 'root' menu.  This 
would be used (for example) if you had two sets of menus, 
one for ascii and one for ansi.  The main menu would have a 
question asking what type of menus you want.  The command 
would be a command 9, and the new menus (ansi or ascii) 
would then be the new 'root' menu.
      And, of course a few bug fixes here and there.  See 
the changelog for more information.

     To update from Rocat 0.80, you need to update your 
bbsinfo file to reflect the new options found there 
(CHECKMAIL and FUDGETIMELIMIT).  Use the example found in 
the archive to make sure you've got everything.  Other than 
that, there isn't anything more to be updated.


   Updating from rocat-0.85
     The major change of the BBS from 0.85 to 0.86 was the 
inclusion of a language object that interfaces with the BBS 
to show the user the language that he wishes to use.  Due to 
this, I needed to have the capability to select the language 
on a user-by-user basis.  I've added the name of the 
language file into the userlog database in line 3 (C).  If 
you're running 0.85, you'll need to edit your userlog file 
to add this filename.  I've included a utility called 
userupdate that will update your userlog file and save it in 
a file called userlog.new.  It does not overwrite the 
userlog file.  You must manually move the userlog.new file 
to userlog after checking to make sure things are OK.  (I 
don't foresee any problems)
     I've added a feature that will ask users, upon logon, 
for their first and last names.  It has been reported that 
the BBS will incorrectly put users with only one entry in 
the gecos (real name) field of the passwd file into the 
userlog with a bad first or last name.  If the BBS can't 
figure out the passwd entry for these users, it will now ask 
them what their first name and last name are.  Note that 
there is no 'badword' checking on these entries.  Note also 
that the BBS does not update user's information after the 
initial log-on.  This means that users that already exhibit 
this problem will have to be corrected manually by the 
SysOp.
     There have been many small enhancements to the BBS.  I 
won't go into them here, but the BBS should simply work 
better than it has in the past.


   Updating from rocat-0.86
     There were some very major changes in 0.90.  The menu 
system is now much easier to setup, and, ANSI color support 
is now available.  The major change with regard to upgrading 
was the userlog file.  At the end of line D, there is now an 
expiration date.  This is used when checking whether to 
reset the user's time to default.  
     The userupdate function has changed to automatically 
update the userlog file for you.  Enter the following (as 
the BBS administrator) to update your userlog:
     userupdate 0.86
     This will update the userlog file.  However, it will 
not replace your existing userlog file with the updated 
version (for safety).  Copy the existing userlog file to 
userlog.bak (or something similar) and then move userlog.new 
to userlog.  The 0.90 version of Rocat will then function 
normally.
     One other item must be updated.  The bbsinfo has 
changed to define default colors and attributes for the BBS.  
I'd recommend saving your old bbsinfo configuration file and 
starting fresh with the one supplied with the BBS.  Of 
course, you can cut and paste if you feel confident you 
won't miss anything.

   Updating from 0.90-0.92
     Updates from 0.90 to the current revision basically 
entails replacing the bbsinfo file with the new version.  
Use the following to update:
     1.  Save a copy of your existing bbsinfo file.
     2.  Copy in the new bbsinfo file.
     3.  Edit the bbsinfo file to add your existing 
information.


   Updating from 0.92
     In general, the same process as above should be used to 
update from 0.92 to 0.95.  There are a number of files that 
you'll want to add:
     /bbs/config/roomnames
     /bbs/admin/clubfile
     Note that both are optional.  See the chat section for 
more information about these files.
     In the latest Slackware, the useradd and groupadd 
programs are no longer avaailable.  Due to this, the way the 
BBS uses the 'new' user account and how the BBS operates has 
been changed.  You'll want to update the following scripts 
with those found in the distribution:
     /bbs/bbs
     /bbs/scripts/login.scr
     /bbs/scripts/addbbsuser
     In addition, you'll want to reconfigure the 'new' user 
record.  See the 'new' user setup for more information.  
Basically, the 'new' user is no longer an alias for the 
'root' user.  The 'new' user may be a normal (non root) 
user.
     There is now an additional program, anu, that is 
installed to replace the useradd function.  It must be 
installed by the root user for the BBS to function 
correctly.  See the section on installation for more 
information.

   Updating from 0.95/0.96
     The move from 0.95/0.96 to 1.0 isn't trivial.  I've 
added some very serious features to the BBS that, if not 
done correctly, will make your BBS stop working.  The pieces 
that have to be done are:
     1.  Install shadow passwords.
     2.  Convert your userlog using userupdate.
     3.  Installing a new /bbs/bbs script.
     4.  Installing the new programs (anu, Rocat, etc).
     5.  Installing the new bbsinfo file.
     6.  Creating new directories.
     The above steps, in detail:

     1.  Install shadow passwords.  See the section on 
shadow passwords for more information.
          Note:  the 'new' user record in /etc/shadow must 
be deleted.
     2.  Install new /bbs/bbs script.
     3.  Install new programs.
          1.  Kill all bbs daemons running.  (errlogd, 
rochatd, robcastd, ropchatd)
          2.  Delete the existing 'anu' program.  
               su 
               <root password>
               rm $BBSDIR/bin/anu
               exit
          2.  'make install' from the bbs source directory 
(as shown in the directions above).
          3.  su to root
          4.  'make install.anu'
          5.  Copy all new scripts to the /bbs/scripts 
directory.
     4.  Convert your userlog using userupdate.
          1.  /bbs/bin/userupdate -v 0.89
          2.  Follow the directions at the end of the 
update.
     5.  Install new bbsinfo file.
          1.  Save your existing bbsinfo file.
               cp /bbs/config/bbsinfo 
/bbs/config/bbsinfo.save
          2.  Copy the new bbsinfo file to /bbs/config.
          3.  Edit the new bbsinfo file to reflect your 
current BBS configuration.
     6.  Create new directories.
          1.  mkdir /bbs/spool
          2.  mkdir /bbs/spool/door
          3.  chmod 1777 /bbs/spool/door
     
     If you have problems, send me a message.  It's very 
difficult to test updating due to the amount of work to tear 
down and rebuild a BBS.


   Updating from 1.0 to 1.02
     1.02 is a very trivial update.  In particular, if you 
have 1.0 running, replacing the following files is all that 
is required to update:
     1.  Unpack the source in /tmp (or some other 
directory).
          cd /tmp; tar xvfz ~/rocat-1.02.tar.gz
     2.  cd to the Rocat src directory.
          cd rocat-1.02/src/rocat
     3.  make install.bbs to install the bbs program.
          make install.bbs
     4.  Copy the anu.C.shadow to anu.C.
          mv anu.C anu.C.noshadow
          cp anu.C.shadow anu.C  
     5.  make anu
          make anu
     6.  su to root
          su
          <enter root password>
     7.  make install.anu
          make install.anu

     This should update your BBS to the latest revision.
     
     Notes:
     1.  The BBS is now configured to use the BOLD default 
attribute.  This allows ANSI users to view the screens more 
clearly.  (generally, the normal color attribute is too dim 
for DOS ANSI users)  Since the bbsinfo file hasn't changed 
in format, no changes are necessary.  However, the strings 
compiled into the BBS for <continue> and others now use a 
dim attribute.  (a bold attribute in a string combined with 
a bold attribute as the default results in dim when bold is 
selected rather than bold).  To change this, edit the file 
lang/bbsstring.h in the Rocat 1.02 source area.
     2.  The files listing now takes large windows into 
consideration.  If your window is larger than 24 lines (and 
you've told the BBS to use the larger size), files listings 
will fill the entire window rather than just 24 lines.
     3.  'anu' had a bug that resulted in incorrect shadow 
password numbers being assigned.  Why it ever worked is 
beyond me; however the bug has been fixed in the new 
version.


   Updating from 1.02 to 1.03
     The following features were added to the BBS between 
1.02 and 1.03:

    Setting dim and bold didn't work correctly in menus.
     The CDROM sections aren't being parsed for long 
   description correctly.
     The text in edit user settings is not lined up 
   correctly.
     Add auto probing for ansi.
     Add capability to display ansi text files and text 
   files, based on the capabilities of the user.
     Add a percentage indicator to the files area listing 
   so that the user knows how far into the section they are.
     Rewrite bbsinfo to cache all possible information to 
   reduce the number of file reads.
     Add a display of the following upon logon:
          caller number
          last callers (name, tty number)
     The flags in a menu are specified incorrectly in the 
   manual and don't work correctly in the menus themselves.
     Convert the systemx.msg into a subdirectory for 
   bulletins.  Bring up a list of bulletins upon logon 
   rather than making the user view each message each time.
    Credited time in talk with the sysop (and credit_chat 
   is on) wasn't being credited.

     The above doesn't affect the installation of the BBS 
greatly.  However, follow the instructions below to update 
to 1.03:

     1.  The system bulletins are no longer named 
system[1-3].msg.  Rather than use a finite number of 
messages, I've combined all system-wide text files into a 
single menu.  See the next item for more information.
     2.  The BBS now starts with a menu named 'bulletins'.  
It must exist for the BBS to run.  In particular, copy the 
bulletins menu from the distribution.  Edit this menu to 
your tastes.  The menu represents a list of the text files 
found on your BBS that relate specifically to the BBS.   The 
current bulletins menu:

    <1> System Notes (Please read!) 
    <2> New Files (updated nightly)
    <3> Most Popular Downloads (updated nightly)
    <4> New User Information
    <5> System Standards and Rules
    <6> How to access Adult files areas
    <7> Rocat BBS Information
    <X> Exit Bulletin Menu

     See the menu for more information.  Basically, it is 
just a lead-in into the original 'main' menu.
     3.  Add the following lines to your bbsinfo file:

# set the below to 1 to show the caller the last 5 callers 
of the 
# bbs
 
 SHOWLAST      1

     The above refers to two files new to 1.03 found in the 
admin directory:

     Filename  Description
     recent_callers A description of the last 5 callers of 
the BBS.
     callers        The number of callers of your BBS.

     To create these files, do the following:
          1.  Become the 'bbs' user.
          2.  cd /bbs/admin (or $BBSDIR/admin)
          3.  touch recent_callers callers
          4.  chmod 664 callers
          5.  chmod 664 recent_callers
     4.  At this point, kill the errlogd and the chat 
daemons, as necessary.  Rebuild the BBS and re-install 
(follow the install instructions above if you don't 
remember).  

   Updating from 1.03 to 1.05
     The following features and problems were addressed in 
1.05:
  Created a startup and shutdown script for the BBS 
   daemons.  It resides in $BBSDIR/bin/rocat_daemons.    
  Due to changes in previous versions, the copying of 
   .profile, .cshrc, etc. weren't possible in the addbbsuser 
   script.  This has been moved into the anu program (since 
   it's running as root anyway).  If the files 
   /etc/stdlogin, /etc/stdcshrc or /etc/stdprofile exist, 
   they will be copied to the user's directory.  Thanks to 
   Doug Hackenbruch for the anu changes.
  Added abort capability to the chat daemons so that 
   debugging may be attempted by sending SIGUSR1 to the 
   process, generating a core dump.
  Fixed: When in an external (via the sysexec object), a 
   ctrl-c, followed by a ctrl-c causes the BBS to terminate, 
   effectively giving the user more time in the BBS that 
   they should have.  (e.g. their time isn't recorded, the 
   program just exits)
  Fixed bug in user delete that caused all users after the 
   deleted user to be deleted. (Thanks to fede 
   <fede@bronzik.quark.it>)
  Fixed a bug in one_download that caused a segmentation 
   fault when the user hit return rather than typing in a 
   filename.
  Changed the bbsipc send() and receive() functions to 
   allow sending and receiving of lines of data.  This 
   allows better interoperability with existing 'net 
   programs (like sendmail).
  Moved the command strings into the language file to allow 
   colorizing the command prompt.
  Changed the maximum error message handled by the error 
   logger to 64K chars (from 255 chars).
  The ansi terminal type doesn't work for 'vi' in RHL.
  The BBS now needs the optional 'bc' command.
  A bug in the long description read function was causing 
   segmentation faults in the machine requirements.  It was 
   one byte off, which caused it to go past the end of the 
   string.
  Turned off SLASH_KEYWORD by default.  The SLASH_KEYWORD 
   define makes it an error for any command to have a 
   backslash with an invalid bbs command.  When serving DOS 
   files, a backslash may be in the description, writing 
   spurious messages to the log file.  (I'd recomment 
   turning it back on when debugging menus)
  The processing of the above SLASH_KEYWORD caused 
   backslashes to be processed incorrectly, resulting in a 
   segmentation fault.
  If you have a PAGER environmental variable set, the 
   system uses that instead of the bbsinfo 'SYSPAGER' 
   variable.    

     The major addition between 1.03 and 1.05 was the 
addition of the database and the messages system.  Use the 
following directions to upgrade your system to 1.05:

1.  Compile and install the database.  Don't forget that you 
must send in the registration fee if you are a commercial 
site.
2.  Create the messages database and related message areas.
3.  Recompile the BBS and reinstall it.  The BBS should 
install seamlessly.
4.  Merge the new bbsinfo file with your current bbsinfo 
file.  The following have changed within the bbsinfo file:
     1.  The COMMAND string is no longer used.  The command 
string has been moved into the language file.
     2.  The following are new:
Item           Description
LOG_MAIL_IMPORT     Should the BBS log email being imported 
to the BBS?
MAIL_FORWARD   Should the BBS automatically create a 
.forward in a new user's home directory?
BBS_NAME       The name of your BBS (for taglines)
REG_SENTENCE   Your registration sentence.  
REG_KEY        The key that determines whether the BBS has 
been registered.

5.  Copy all utilities and scripts that are not currently in 
your $BBSDIR/bin and $BBSDIR/scripts directory.  
6.  You must install the 'bc' utility if you haven't already 
done so.  It's used by the database scripts for computation 
of the maximum message text size.
7.  Copy the editors file from the distribution (in the 
config directory) to $BBSDIR/config/editors.  Edit the file 
to remove those editors that your BBS does not support.

     At this point, your BBS should be up and running at 
revision 1.05.  
          

   BBS revision history (and future)
     The following documents where the BBS has gone.  Please 
take future version information with a grain of salt.
Version        Notes
0.70      Not publically released
0.75      First publically released version
0.80      Added CD-ROM file section support and removed some 
extraneous information
0.85      Separated the BBS strings to separate files for 
easier foreign language
          configuration
0.86      Created language object to display the language 
that a user selects upon initial
          logon.
0.90      Re-design of the menu system to allow the 
following capabilities:
                 'Include' of menus.  This allows creation 
of menu templates
                 Color changes
                 Macro definitions (for common strings)
0.91      Update of color system
0.92      More updates and bug fixes
0.95      Introduction of the Chat subsystem.
1.00      Account expiration/validation/limitation, shadow 
passwords, bug fixes.
1.01      Small enhancements, removal of shadow passwords as 
mandatory, bug fixes.
1.02      Small bug fix in the english file.
1.03      Bug fixes, speed improvements.
1.05      Introduction of the message system.  
Future (potential)
1.10      Userlog  moved into database.
1.15      Files areas headers moved into database, along 
with messaging-style files viewing.
1.20      Introduction of a administration GUI.
1.25      Addition of keywords to the menu system.
1.??      Introduction of a fully-featured BBS monitor

   Conclusion
     I hope this document has been successful in its 
purpose:  Introducing the Rocat BBS system and showing you 
how to build your own BBS.  In future versions of this 
document I want to put the following things into this 
document:

  A walk through for those who have never run a BBS before.
 More pointers on how to setup the BBS for Linux
 More examples

     Well, that's where it has to end.  This BBS isn't 
finished, but it works really well.  I think the BBS has 
some of the most powerful capabilities I've ever seen.  
This, coupled with the native programs and services 
available on Linux (Unix) make the BBS a very powerful 
system.


   To Contact Me
     Should you run into difficulty, I will be available to 
answer one question prior to registration.  After that one 
question, I have to require registration.  That allows me to 
concentrate on the customers who feel my BBS is worth paying 
for.  I'm sorry if you do not agree with this, but it takes 
a LOT of time to develop this BBS, and I get little 
recompense.  
     If a question is either obvious (RTFM) or not on the 
topic of the Rocat BBS system, I will send it to /dev/null.

     I may always be contacted at my BBS:
          The Roman Catacombs
          (303) 429-8914 (v.32bis)
          (303) 429-6257 (v.34)

     And, of course, Internet mail:
          shaw@fmsoft.com



   The Rocat Mailing List
     There is a Rocat mailing list available.  To subscribe, 
send 'subscribe' in the body of a message to:
          rocat-request@manwe.fmsoft.com
     This will subscribe your email-address to the Rocat 
mailing list.  The mailing list is used for up to date news, 
patches and utilities that other SysOps have come up with 
with respect to the Rocat system.  I highly recommend 
subscribing to this list.  Many bugs are reported to the 
list first.  If you find that you're having trouble, the 
list can show you that there is a fix available (perhaps 
even show you the fix before you pull your hair out).


   Appendix A: The Rocat BBS List
     The following is the list of existing Rocat BBS systems 
operating worldwide.  It is not complete.  If you want to be 
on the following BBS list, please email your information to 
me.  If you have mailed your information to me in the past, 
please pardon my forgetfulness and send it again.

BBS Name       Country        BBS Phone Number    SysOp     
Version   BBS Focus
The Roman Catacombs USA       (303)429-8914  Gregory Shaw   
1.05 Linux, BBS Development
JPUSA BBS      USA       (312)878-6030  Doug Hackenbruch    
1.03 Jesus People USA Covenant
?              South Africa   +27 11 673 1321     Calvin 
Browne    0.91 ?
Gobbler Net Classic Games     USA       (701) 222-0429 Bob 
Newell    ?    Unix/Online Games
Bronzik Unlimited        Italy          (unavailable)  
Federico Pelllegrin 1.05 ?
di CyberValley BBS  Italy          0039-55-983302 Leandro 
Noferini  1.05 ?

   Appendix B: Programming Externals
     Programming of BBS External programs can be very 
difficult without explanation on how to do so, and, some 
example source code to use as a basis.
     Included with rocat-1.05 (and newer) is a number of 
applications that can be used as examples on how to prgram 
external applications (games, time banks, voting booths, 
etc).  
