bbs100 by Walter de Jong <walter@heiho.net> (C) 1997-2015

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 administrate
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. Unless the cache is disabled, 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 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/ have special meaning:

    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'.
    Mind that the etc/param file is rewritten by the BBS itself. Any
    additional comments will be lost.

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

    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.
    It is also possible to upload the file (use copy/paste) from within the
    Sysop menu, in the Screens section.

    etc/categories
    
    Contains list of room categories. Can be managed from within the Sysop
    menu.

    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. You can choose whether you want
    existing users to be able to connect or to lock out the entire site
    indefinately. Do not edit this file while the BBS is running, use the
    Sysop menu to edit wrappers.

    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/nologin.is.active

    This file exists when nologin is active, or you can create it when you
    want it to be active upon startup. When nologin is active, only superusers
    can login.

    etc/pid

    This file contains the pid of the BBS main process. The bbs startup
    script uses this file to kill the BBS when you want to stop it.

    etc/resolver.xxxx

    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 BBS must have been built with --enable-debug for this to
    work.
    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, but
    you can try setting _XPG=1; see the IRIX nm man page)

    etc/feelings/*

    These are feelings, which are displayed when a user presses '*'.
    Feelings can be added, removed, edited, etc., from the Sysop menu.


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 select
his or her timezone.
The default timezone that new users get is configurable, but I strongly
suggest it be set to 'other/GMT'.

The log files display the system's 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.
The maximum number of messages is <max_messages>. By default, this is set
to 50. This number can be set on a per-room basis. To do this, go into
superuser mode and enter the room config menu.
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_msgs> mail messages in
the Mail> room. <max_mail_msgs> is in the param file, its default is 50.
If a user has more than <max_mail_msgs> 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. Messages will not be saved when
the disk is full 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 needed 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