bbs100 by Walter de Jong <walter@heiho.net> (C) 2004

bbs100 COMES WITH NO WARRANTY. bbs100 IS FREE SOFTWARE.
bbs100 is distributed under terms described in the GNU General Public License.

This is bbs100, yet another clone of the popular DOC (Dave's Own Citadel)
style BBSes. If you've never used such a BBS, I suggest you try MatrixBBS
before installing bbs100.
MatrixBBS is at telnet://matrix.whacky.net, and it has been one of the
primary beta test sites.

You should READ THE LICENSE before proceeding.

You probably want to read the INSTALL file, unless you've done so already.
Here are some things you should know about bbs100.

DOCUMENTATION
The documentation on what bbs100 is, how to operate it, and how its
internals work is quite poor. My apologies for this. I suggest you carefully
read the README, INSTALL, NOTES (if any), and look around in the bbs100
directory tree. I also suggest you read the online help, built into bbs100.
If you are not a user of DOC-like BBSes, I strongly suggest you try using
MatrixBBS at telnet://matrix.whacky.net before attempting to administer
bbs100.


CACHE
bbs100 uses a file cache in memory. By default the cache is set to 256
files. This means the BBS process will keep a maximum of 256 files resident
in memory while running. This also means that after startup, the BBS process
will start to grow as the cache is filling. When the cache is full, it will
use an LRU algorithm to refresh the cache. The memory use of the BBS process
should remain roughly the same from this point on. Because it is pointless
to keep files in memory when nobody is using them, there is also an
expiration timer. This is the cache_expire parameter and is specified in
minutes. The maximum cache size can be set dynamically from within the BBS,
from the Sysop->Parameters->Maximums menu.

IMPORTANT
As a consequence of caching, you cannot edit ANY userfiles or filed messages
at Unix level. User files remain in memory even after they have logged off
the system, so if you use an editor to edit the file at Unix level the changes
will be lost whenever the cached file is synced to disk.
Always keep in mind that any file under users/ and rooms/ might be present
in the cache.
Sysops have the option of clearing a file from the cache. To do this, choose
'uncache file' from the Sysop menu. The filename is the Unix filename,
relative to the BBS' basedir. For example, to clear the user file of a
user named 'Walter' from the cache, enter users/W/Walter/UserData as filename.

Files under etc/ are not cached. However, they should be treated in a special
way:

    etc/param

    The param file is loaded as first configuration file at startup.
    It contains parameters that can be set to tune the system for you.
    The param file can only be edited when the BBS is not running. To change
    the values in the param file at runtime, use the sysop menu 'Parameters'.

    etc/login, etc/logout, etc/motd, etc/crash, etc/first_login,
    etc/help.std, etc/help.config, etc/help.roomconfig, etc/help.sysop

    These files are 'screens' that are displayed to the user at certain times.
    They are loaded at startup and kept in memory at all times. You can edit
    them using a Unix editor, you should use the 'reload <file>' option in
    the BBS' Sysop menu to make the new message active.

    etc/GPL

    This is a copy of the GNU General Public License.
    Users can read it by pressing Ctrl-G.

    etc/local_mods

    This is file should contain a list of modifications, if the site runs
    a modified version of bbs100. Users can read it by pressing ']'.

    etc/banished

	Contains names of users that can't login. Do not edit this file while the
	BBS is running. Use the Sysop menu to <B>anish or unbanish users.

    etc/hostmap

    Contains a description of the domain a user is connected from. As a
    security feature, users cannot see the IP address of another user.
    Only the super user(s) can see where people are from.
    However, it is possible to set a description in the hostmap file,
    which will be displayed in the user's profile info. If you don't want
    anybody to see any info on where someone is from, you can simply remove
    the hostmap file and then this feature will be disabled.

    etc/hosts_access

    Contains 'tcp wrappers' to lock out sites. When you lock a site, no new
    accounts can be created from that site. Existing users will be able to
    connect. Do not edit this file while the BBS is running, use the Sysop
    menu instead.

    etc/nologin

    Contains the message displayed when 'nologin' is active. This message
    can be edited at any time, it is loaded by the BBS when nologin is
    activated using the Sysop menu. When nologin is active, only superusers
    can login.

    etc/pid

    This file contains the pid of the BBS guard process. The number indicates
    the port number the BBS is running on (you can run multiple servers on
    different ports). Do not edit this file.

    etc/resolverxxxx

    This is a special file used by the resolver process which should not
    have been left behind. You can safely remove this file at any time.
    xxxx should be the pid of the dead resolver process.

    etc/symtab

    This file contains the symbol table of the BBS program. This file is not
    needed; the BBS will work even if the file is missing. However, if it does
    exist, the file is loaded and used for making stack dumps when the BBS
    crashes.
    The file can be created by running 'nm', e.g. 'nm -P bin/main >etc/symtab'.
    The -P option to nm is needed on most systems to produce a POSIX.2
    compliant symbol table.
    (The format should be: <symbol name><type><address in hex><[size in hex]>.
    Note that IRIX nm does not produce a POSIX.2 complaint symbol table.)

    etc/feelings/*

    These are feelings, which are displayed when a user presses '*'.
    Feelings can be reloaded from the Sysop->Parameters->Reload menu.

    etc/zoneinfo/*

    These are timezone files in plain text format. They are used by
    the world clock in the calendar (press 't' for Time).


SIGNALS
The BBS responds to certain Unix signals.

    SIGHUP     Toggles nologin status
    SIGQUIT    Performs a reboot   (in 5 minutes)
    SIGABRT    Performs a shutdown (in 5 minutes)
    SIGTERM    Performs a shutdown (now!)
    SIGUSR1    Scans the Mail> folder of every online user for new mail.
               This was implemented so e-mail can be spooled into the
               BBS. However, this introduces a race condition (the message
               number), so be warned.

Most other signals are either ignored or linked to the crash handler.


TIME ZONE
By default, the time displayed by the BBS is in GMT (Greenwich Mean Time).
This may seem confusing, but the users of the BBS can connect from
anywhere in the world. In the Config Time Zone menu, the user can enter his
or her local time to 'synchronize clocks'.
Note that the BBS does not actually reset the clock, it just calculates a
time displacement for this user, and uses it to adjust the clock for this
user. The BBS is intelligent about whether the user has a positive or
negative time displacement relative to GMT, but problems occur on the date
line; the BBS cannot tell whether it's -12 hours on day 1 or +12 hours on
day 2. If a user has a time displacement of 12 hours, the BBS will ask him/her
if the date is correct.

Americans don't seem to like 'military time' very much. Especially for them
there's an option in the Config menu to switch from 24 hour clock to 12 hour
clock (with AM and PM). AM means 'in the morning' (after midnight and before
noon), and PM means 'in the evening' (after noon and before midnight).

Mind that the BBS doesn't know anything about daylight savings time. If the
clock the machine runs on uses daylight savings and the user does not, the
clocks will display a difference of an hour when daylight savings apply and
the user will have to re-synchronize.
The world clock in the calendar function is smart; it does knows about
timezones and when daylight savings are in use. Because the users may
have to re-synchronize, it is possible that the world clock displays the
wrong timezone to the user. This is a known issue and exists as long as
users are unable to input what their timezone is.

The log files display local time in the format MM DD hh:mm:ss.


TRASH DIRECTORY
The trash/ directory contains 'nuked' users and rooms. You can remove users
and rooms from the BBS by making use of the options in the Sysop menu.
Nuked users and rooms can be re-installed from the trash/ directory by hand,
but be careful. Someone else might have created a new account with the same
name in the meantime, or another room can have been created using the same
room number. Rooms cannot be re-installed in a live running system ; the
BBS needs to be rebooted.
Deleted messages are not moved to trash/, they remain in the rooms/ directory
but they are flagged as 'deleted'. Deleted messages can be undeleted by using
the <U>ndelete option in the BBS.
Old messages expire from the room automatically, they cannot be undeleted.
Old unread mail messages are kept until the user has actually read them, so
it is possible that some user has more than <max_mail> mail messages in his
Mail> room. <max_mail> is in the param file, its default is 50.
If a user has more than <max_mail> Mail> messages, the message will expire
immediately after the message has been read.


EXPIRING OLD ACCOUNTS
This is not done automatically. There is a script named bin/expire_accounts.sh
that can be used to move unused accounts to the trash/ directory.
You will have to empty trash/ by hand.
By default, expire_accounts expires accounts that have not been used for 100
days. So, all a user has to do is login once every 100 days and he'll be safe
from expiration.
To change the amount of days, edit the expire_accounts script in the BBS'
bin/ directory.


TAKING CARE
It is recommended that you make daily incremental backups of your BBS,
especially of the directories users/ and rooms/, and do full backups weekly.
You never know what may happen, and your users will not like it if your
BBS disappears in a disk crash one sad day.
You also don't want to run out of disk space. At the moment, bbs100 is very
bad at handling full disks: messages will not be saved correctly and as a
consequence messages will be lost. Make sure you have enough free space 
(cleaning up old log files usually is sufficient) and you will be fine.


SITES RUNNING bbs100
There is a list of sites known to be running bbs100. This list can
be found on the web at http://www.heiho.net/bbs100/sites.html
If you are running bbs100 (in a modified way or not) or know of a site
running bbs100, please mail me stating the IP address and name of the BBS. 


HISTORY
The following is a story, a history of how I came to write bbs100.
Most people like to skip this part the README.

Back in 1994, when I was studying computer science, BrintaBBS was founded.
We started out with a copy of an old version of DOC, which was greatly
improved by a number of people, including myself. The BBS became quite
popular over a very short amount of time, and soon the machine it was
running on at the time (a i486/66 MHz with 32 Mb RAM) was not large
enough. The load was high and the machine got slow.

One day, a friend gave me a tiny source code of a name resolving server
for a MUD. It was a single process daemon that could have multiple
connections all at once. I hacked away in it and turned it into a tiny
chat server. It was crap, but it was fast and it hardly used any cpu
time. It was then that I made my first designs for a single process
DOC-like BBS.
I spent the summer of 1995 programming an implementation of some designs,
but it never worked and it was never completed. My knowledge of Unix wasn't
very good at the time (I coded C and assembly for MS-DOS), but because of
the BBS I got into Unix.
Later, the ideas were worked out by others and implemented in a whole new
rewrite of BrintaBBS. It worked perfectly, it hardly used any cpu time and
the load remained quite low. One of the drawbacks was that it wasn't very
stable in the beginning. The stability improved over time, but the network
at the university got slow so the lag got worse anyway. Another problem was
that the code was incredibly hard to understand and it was far from portable.
The author kept the code to himself, the BBS management group got into lots
of arguments, and eventually I left BrintaBBS in November 1998.

In the meantime, I had been working on a number of BBSes, chat MUDs, and
IRC-like chat servers. Most of them were only half-finished, and none
of them ever seriously ran as an online service.
In the beginning of 1999 I set off to write some big and sophisticated
online service, a re-invention of usenet on steriods -- if only because the
new millenium needs something new. The ideas were wilder than ever and the
code grew into something monstruous. As you may guess, the sophisticated
online service was never going to be realized.
At some point I quit and started hacking in a single process chat server
I originally wrote in 1997. After a while, it suddenly took shape and
bbs100 was being formed. Hardly having any time at all to work on it,
it still took me over 6 months before it was usable.

The first distribution under GPL was not until August 2000.
I hope you'll enjoy it.

Greetz,

    --Walter <walter@heiho.net>
             http://www.heiho.net/bbs100/

EOB