//////////////////////////////////////////////////////////////
// Onyx Sidewinder Bulletin Board System 0.10 Alpha release //
//////////////////////////////////////////////////////////////
by Sten P6ldma (exile@chamber.ee) 6 = o with an accent mark above it.
Chamber Systems Research Department - www.chamber.ee
Onyx Sidewinder homepage - www.chamber.ee/os

___________
Index
===========

1. Disclaimer
   1.1 Disclaimer of Onyx Sidewinder BBS
   1.2 Disclaimer of this documentation
   1.3 Warranties
2. Introduction
   2.1 Purpouse
   2.2 Features\Non-features
   2.3 Future
   2.4 Future releases, updates
3. Installation
   3.1 Installation options
   3.2 Problems
   3.3 Modem usage
4. Porting
5. Configuration
   5.1 The basics
   5.2 Automated maintainance
   5.3 Graphics
   5.4 Doors
6. Running the system
   6.1 Remote running (telnet)
   6.2 Modem running
7. Security
8. Misc
   8.1 High-Tech Knowledge
   8.2 Credits
   
#########################################################
## 1. Disclaimer                                       ##
#########################################################
These disclaimers are strict and are not open for conversation. Although
Chamber Systems leaves some space for itself to change the disclaimer
policys whenever it seems fit.

1.1 Disclaimer of Onyx Sidewinder BBS
=====================================
Onyx Sidewinder BBS or OS BBS for now on is originally modified from Black
Box BBS by Walter Heukels (wmh@xs4all.nl) with his personal permission was
OS BBS development and research started. Although OS BBS is owned by
Chamber Systems (www.chamber.ee) and is programmed and maintained by Sten
P6ldma 6 = o with an accent mark above it. (exile@chamber.ee). You can
distribute the intact package of this software freely and you can modify
it for your needs (this is why it's a source package) but after the
modification YOU CAN NOT DISTRIBUTE IT, either under OS BBS or any other
name. So most partly this license falls under the GPL but nore entirely!

1.2 Disclaimer of this documentation
====================================
This documentation is copyrighted and you can not change it in any ways.
This is the property of Chamber Systems and maintainance of this doc is
also organized by Chamber Systems. Changing this doc in any way is against
copyright laws. The credits of this doc goes to Sten P6ldma 6 = o with an
accent mark above it and to Walter Heukels who wrote the original Black
Box BBS documentation. Because of English not being the native language of
the author, mistakes should be looked as a feature, not as a bug :)

1.3 Warranties
==============
This program is developed by Chamber Systems and Sten P6ldma. As it is a
beginning project (it fill be ever after) the idea of this project is to
make a workable prototype of BBS to run on chamber.ee domain and server
selected clients. Therefor we don't take any responsibility to any hacking
pracking blowing up computer stuff. If you use it, it's your problem, not
ours. The only thing we can promise is that we haven't put any backdoors
or such to our code (please read the source) although i don't promise you
that the package you may hold is authentic one. That's why make sure you
have downloaded this package from OS BBS homepage or qualified mirror
submited by us. You can be suprised how many bad people there are out
there. Don't EVER accept a copy of OS BBS from a friend :) it's still a
small package so DOWNLOAD IT !!!

#########################################################
## 2. Introduction                                     ##
#########################################################
Onyx Sidewinder BBS or OS BBS for now on is a completely free and full
bulletin board system solution software for Linux platform. The
development was started from Black Box BBS by Walter Heukels because that
project was already stopped and we saw that it is a great oportunity to
build up a decent package from this, maybe even included to Linux
distributions one day, who knows. OS BBS is being developed in Chamber
System Research Department by Sten P6ldma 6 = o with an accent mark above
it. There are main goals for this project that we try to fullfill. They
are as fallows:

    * Free - as from other packages to Linux that are worth to use, this
      package is kept completely free. As it is specially developed to
      Chamber Systems needs @ www.chamber.ee
    * Telnet - the main protocol that this system is suposed to be using.
    * Flexibility - it has to be configurable and as easy to understand as
      possible.

This list is not final and is changed whenever we see it fit.

2.1 Purpouse
============
The purpouse of OS BBS is to serve as a telnet based bulletin board
system. It is widely configurable and supports doors. It serves as the
sysop sees it fit, either serving as a news reader to a server or a
complex file serving front-end bringing the menus to the end user using
colorful ANSI screens or ASCII files. 

2.2 Features\Non-features
=========================
These are the main features of OS BBS:
* Graphical (ANSI) menus and simple hot/key combinations without a need to
press Enter.
* Intigration with Unix system as much as possible. You can use your
favorite Unix tools (sed etc.)
* Sending and receiving Internet e-mail. For receiving you still need a
static connection to the Internet, dynamic connection is untested at this
time and will probably bring some complications to the OS BBS work.
* Support of powerful menu language. That means you can make the bbs look
like you want without recompiling the howle bbs system.
* File transfer protocols
* Crypted password security
* Doors
* Special guest user access
* Telnet support
* Modem support
* Multilingual support

Non-features:
* No GUI for the Sysop, if you hate text editors then you have hard time
geting this system to work as everything (almost) is made through text
editor, this is due to the flexebility of this system as there are no
static configuration files and the user can add to configuration fies
whatever he sees fit. That's why a configuration tool would be quite hard
to acomplish

2.3 Future
==========
Where is this package going ? The main idea of this version was just to
overtake the Black Box project and adapt it to work with telnet as giving
it an outlook of its own. That means that in this version there are not
many new features but I am drawing a sketch how this package should look
like at the end of this year (1999). I will probably start with the bug
eliminating project I have in mind, that means i will try to skoop the
bugs and kill them as I can, also I try to make sure that it still
compiles after the bug elimination. Also besides that i'm going to
cross-code it using perl why ? Because perl does not need to be compiled
and it makes a great CGI frontend. Geting the idea ? The idea is to make
the bbs also available through the WWW using the data files of the OS BBS.
This way the user can also have a nice point-and-click-interface what all
users are dreaming to have anyway. Also this is a good way to Sysops to
use real graphics on the BBS.

Although i'm planning to brin OS BBS to the WEB I'm not going to forgot
the telnet based bbs. In my view there are going to be things that can't
ever be ran through the Web, like your chosen doors for example. The web
will support only the File Transfer section as the Messaging base system.
That is all, for now.

What this system will probably never do for you? This is already written
about in the Non-Features section. OS BBS will probably never support GUI
administration feature, although the user gui to the web is not so hard to
do the sysop tools are harder, this is because of the flexibilities of the
configuration files. There will be a some sort of User administration
tool, because if you have 500 users than it's hard to edit users with a
vi. But it will draw some limits to the sysops, they cannot change the
format of the users file or the administration tool will not work. Anyway,
this is not a problem for this version as there are no tools available
right now. I guess we'll see the future soon.

2.4 Future releases, updates
============================
This howle project is ran by Chamber Systems and the research and
development of this package is made in my free time, that means when i
don't have nothing else to do, I work in Chamber Systems as the Chief of
Technology and my job is to keep all the servers happy and administrate
the users and domains, that's a peace of work considering that I still
study. That's why I cannot promise anything, when the bugfix or new
release will be made available.

I still promise that I have'nt planned dumping this project in any way
soon because the development of this package depends on the needs of
Chamber Systems. I still hope that you won't be paniced if i don't update
the OS homepage as often as I should because it just takes too much energy
from me.

#########################################################
## 3. Installation                                     ##
#########################################################
First, please read the REQUIRENMENTS, my.problems and your.problems to
make sure you do have the things to install this package. The step by step
instructions of quick installation is in INSTALL file. All these files
should be in the doc directory, if you are missing these files then
something fishy is going on but you can get the files separately from
www.chamber.ee/os - the OS BBS homepage

3.1 Installation options
========================
Although you can compile the program with default setings I have added a
small addon feature to OS BBS. In default newusers are allowed, but I got
some mail that some users might want to run a closed BBS. I figured out
that I guess there aren't many sysops who do want to run a closed bbs
because this way you even can't add users to the database, you have to add
it manually or wait for the user administration tool.

To disallow new users, before compiling edit nlogin.c in the main
directory and uncomment the lines 373-376 and comment the lines 377-379,
that's it.

3.2 Problems
============
Actually right now i'm not going to cover the problems here because the
my.problems and your.problems files are being kept updated anyway. Please
read these files concerning the problems compiling this package. Thanks.

3.3 Modem Usage
===============
As far for the installation you don't have to make any changes before
compiling. The modem has to be available to the system and you have to
know the device to use, for that you have to consult the Modem HOW-TO's.
Please look 5.1 The Basics of confiuration to see how to configure the
inistrings of the modem.

#########################################################
## 4. Porting                                          ##
#########################################################
This package is developed and tested under Linux Slackware distribution,
any other *x systems are not tested or supported, although you can try to
install it or port it be my guest but please contact me. I'm sorry to say
but I can not help to port this package my self to any other platform as
my available time goes to developing this package to the Linux platform.

#########################################################
## 5. Configuration                                    ##
#########################################################
After the installation of the package the next step is to configure some
files. All the general configuration files of OS BBS is held under data/
direcotry. There are some comments in the file that help you making
changes.

5.1 The basics
==============
Here is described the files held under the data/ directory that are
essential to be looked and changed before running the system

* data/archivers - This file contains the command lines to extract
FILE_ID.DIZ or DESC.SDI files from uploaded archives. Note the absence of
ARJ. Unfortunately unarj is too dumb to understand extraction of single
files.

* data/areas - The main file areas configuration files.

* data/badnames - This is the listing of usernames not allowed to log in
to the OS system. Trying to login using one of these names also counts as
a login attempt.

* data/busy - This file is shown when the maximum number of nodes are
being used.

* data/config - The main configuration file. Variables defined here can be
used anywhere where variables can be used.

* data/initstrings - The control file of the modem, defines the inistrings
sent to the modem. Also configures the speed of the modems.

* data/issue - a file shown before the login prompt.

* data/macros - A set of sysop-chat macros. Be creative.

* data/nodes - contains a list of nodes that osserv will try to keep
running.

* data/protocols - contains a list of file transfer protocols.

5.2 Automated maintainance
==========================
Different from other BBS systems, this bulletin board system doesn't
really need any daily system maintainance. The only thing you have to
watch is what your users are doing and maintaining the user files

5.3 Graphics
============
OS BBS uses ANSI or ASCII files to show the menu structure to the user.
All the graphic files should be placed under screens/ and will be called
from the menu files under menus/ . You should make sure that every file
that is called from menu files are accessible and available to the OS,
otherwise bugs will ocur and users wont see anything. Also note a problem
with some systems who seem to show some ANSI and ASCII screens with
foreign letter not showing the real graphics. This problem can be solved
by typing `setfont -u none' The problem is that a system uses a character
map that is different from the ASCII and ANSI default maping the -u none
tells the setfont tool not to use any character map but show things as
they are. Again this setting could make some problems with some other
programs who again need maps. see `map setfont' for more detailed
information.

5.4 Doors
=========
When it comes to doors then you can use almost any Unix tool that can be
handled through telnet, again, everything is called from menu files. I
still warn you not to use any beta software or software that can be
paniced and gained shell that way. Before adding a door program you should
be avare of it's security. I guess this is the only way your BBS can be
hacked.

#########################################################
## 6. Running the system                               ##
#########################################################
There are two main modes of operation: Modem mode and Remote mode (aka
Telnet mode operation)

6.1 Remote running (telnet)
===========================
Because of the way os is built up (like its predecessor) it doesn't have a
terminal device included inside. That means you cannot just simply run it
as a daemon service or by inetd. Instead, I made it compatible with the
new telnetd that allows different login programs, that is what you need
to run it through inetd - with the help of telnetd. Look at the INSTALL
file for step by step instructions.

6.2 Modem running
=================
To let OS handle a modem, run the system like this:

./os -modem <modem device> <other options>

Make sure you have configured the modem device initstrings first. Look at
5.1 for configurating the basics. When ran like this, modem will wait for
the phone to ring, pick it up, allow a user to log in, and start the
menus/login where everything else will grow on. The modem will transfer
information with the user until the user's time runs out, the user logs
off or the os process gets killed, or then an error is occured. OS will
return the next error codes.

* An error occured before waiting for a call. This usually indicates a
configuration error.

* An error occured with someone online. (Diagnostics are output to
standard error and the system log.)

* os was killed

* the user timed out on input.

* the user's time expired.

* the user has hung up instead of logging off cleanly.

* a segmantation fault happed. If the program dumps its core i want to
know about it, please mail the information about it to exile@chamber.ee

* the caller failed to login properly three times.

* the maximum number of nodes was already active.

* the modem could not connect.

A return value of 0 means everything went alright, and the user logged off
normally. This doesn't happen too often.

##########################################################
## 7. Security                                          ##
##########################################################
Concerning the security issues are a little bit touchy right now but
because it concerns the runner of this bbs then I guess I don't have any
other choise than to talk about it a little

The way OSBBS is build up is to get things to work and not really look at
security, although much safer these days than OS's ancsestor BB, OS
doesn't need a shell so basically a bad guy would not get a shell...
theoretically. The way this is ran is it uses the new telnetd as a "sort
of a shell" but telnetd is build up this way that if the login program (in
this case OS) will get dumped or exited then also the telnetd would end a
session with the user.. Now this security is very nice but is build up
against a program I haven't done. This is the place where you can ask,
what will happen when telnetd does not end session? The answer is that i
don't really know. But at this time every time OS has paniced my telnetd
has ended the session crasefully.

Now...this is the tricky part, we all like doors, but sadly the doors are
the biggest security risk your box can ever have. Although when panicing
OS the telnet will end the session because OS is defined as telnetd's
login program this does not happen if you panic a door program. Now it all
depends on the program but the worst can happen is that a door is paniced
and the door dumps its core and returns the user to the root shell
(AAARGH!!!!)

Now, as said this is also theoretical (sadly) it all depends on the door
program, how it acts, has it got any bugs and how is it build up.

At the end i guess it all comes to this point that you have to be VERRRY
careful when adding doors to this system (i guess this goes to every Linux
BBS system that supports doors) you should read the newsgroups and find
everything about bugs and maybe get couple of patches before adding a door
to OS. As much as the OS itself goes if a user panics the OS then telnetd
SHOULD terminate the session. So i wouldn't really loose your sleep over
it.

##########################################################
## 8. Misc.                                             ##
##########################################################
Here i'm covering the misc. things that don't really fit anywhere to the
docs. I guess if something smart pops up here I'll someday add a howle new
section for it.

8.1 High-Tech Knowledge
=======================

I have to admit, this documentation is as incomplete as the howle package,
but this just gives us more space where to continue. I also know that i
haven't really covered the inside-out of OS - just the basic stuff. Well
the point is that you don't really want to know more as it is still a
working project.

If you like this package and the ideas we are after and you want to know
more then don't hesitate to contact me - exile@chamber.ee or by FidoNet
2:490/246.700 Also I don't say no to extra pair of helping hands. Is it
working with the www, rewriting this grammatically incorrect manual, or
helping with the ideas and the code - it doesn't really matter, help is
needed.

Also by including my contact information I'm like saying that I'm willing
to help you. But don't mail me if you don't have anything smart to say
like "it doesn't compile" and stuff like that. I'm sure that more than 50%
of Linux users won't get this package to compile anyway, but this is just
the way it is. Sorry.

8.2 Credits
===========
Well as always additional credits goes out to BB BBS author Walter
Heukels. Also I would like to thank me, myself and I, and also I'd like to
include Chamber Systems. Also a big thanks goes out to a special person
who actually ownes the Onyx part of the name, and SHE is Onyx!! :) Also I
would like to thank the brave tester who is reading this manual!! You are
a brave girl\boy... Keep it up!!


-- End of Onyx Sidewinder Manual ver. 0.10Alpha -- 28.Feb.1999 --
