
              Ruskean Rein Ritarit (RRR) Spunk Labs presents


                      VuohiMatik v666 Deluxe v0.2.1

                                  by ~g/RRR
                             
                            Released 26.Jun.2000

0. Legal bull
-------------
Released under GNU Public License, see file 'COPYING'. It does
NOT cover the following stuff which comes along in this package:
    - SMODEM
    - X/Y/ZModem
    - Hydracom

For those, see their individual copyright information.


1. Quick preview
----------------
VuohiMatik v666 Deluxe (VMatik, from now on) is a BBS software designed
with large BBS systems in mind. The main goal was to get filearea 
operations which work well on tens of thousands of files online, 
giving end-user an uniform interface to perform quick selections 
and searches on the fileareas using various search conditions.

Yes, you've heard all that before, but what makes VMatik unique 
(as far as I know) as a free BBS software is the fact that the 
database handling is delegated to an external SQL server
(which is not made by me <grin>). This should ensure that the 
bbs data related algorithms are really good, not just something 
that Billy Bob came up with last night.


1.1 Availability
----------------
At the time of writing this, the latest version of VMatik was
available from:

http://www.geocities.com/iwronsky/

If both are down when you're reading this, consult a net
search agent.


2. When to use VMatik?
----------------------
Currently the system is best suited for "filetrade" systems, where
users upload and download according to given "ratios".

Suitability as message writing/reading system might be considered 
adequate. It works, but it isn't up-to-date: Internet newsgroups 
and email are not supported at the moment, and QWK is hopelessly
outdated as an offline reader format.

To really benefit from VMatik, you should have a HUGE system 
with a decent cpu to run it (a slow 586 should do)... Though 
its acceptable to use VMatik just because of its nice features. :)

However, if you want the conservative 100% amiexpress/pcb interface 
ElItEWaReZ system, where everything is JUST as all C00lNeRdZ have 
always used to see them, use DayDream. VMatik has several things done
in a better way, and some stuff has just been dropped out for good.


3. Some features
----------------

General
    - Multinode support
    - Conference based approach, max 64 conferences
    - "Unlimited" number of fileareas in any conference
    - "Unlimited" number of messageareas in any conference
    - "Unlimited" number of users
    - 32 different user access groups. Individual users can be customized.
    - Large amounts of security flags to play with :)
    - Configurable display modes (ANSI color, ISO-latin, etc)
    - External door support, doors can be either VMatik doors,
      interacting with the system variables, or stdio-using executables.
    - Operates as a shell (like "bpfashh"). Any daemon that can be 
      used to provide a shell connection can probably be used with VMatik.
    - Sysop can perversely peek anything the users do online.
    - Simultaneous support for user real names and handles (nicknames)
    - Almost all text strings are located in an ASCII file, so
      you can customize the look of your system or change the language
      without having to recompile.
    - MD5 encrypted user passwords (whatever good that will do)

Fileareas
    - Fast file operations on large filebases
    - Max 4294967296 files on system :)
    - Numbered files (for example, user is able to select files
      505-732 for batch downloading with a single command).
    - Support for two-directional protocols
    - External protocol support (ZMODEM, SMODEM and HYDRACOM are included,
      but you can add your own)
    - Upload/Download ratios, no ratios, freedl files, freedl areas
    - Uniform file command arguments. No matter if the command is
      list, kill, flag or whatever, the argument style remains the same.
    - Bulk describing (Quickly give any number of files the same description)
    - Optional file validation: uploader gets download credits 
      and other users see the file only after Sysop has checked it.
    - FILE_ID.DIZ support
    - Archive support. Archives can be tested, viewed and transformed.
      (Transform: e.g. optimize the archive or convert it from
      format to another)
    - Background upload/download processing. Its transparent to the user.
    - User can choose filelist display orders for individual areas
    - Duplicate checking: Existing files are skipped during the upload
    - Upload redirection: Normally the uploads go to the filearea that
      the user is currently on. However, if redirection is specified
      for the filearea, the uploads go to the specified one.
    - A file backup util which makes shadow directories of fileareas
      until a specified backup media size is reached. Included files 
      will be marked with a backup ID, so they won't be backupped again.
      For example, you can create an ISO image of the shadow directory.
    - Upload onlinetime rewards 

Messageareas
    - QWK offline reader support
    - Fullscreen- & line-editor included
	- External editor support (atleast in theory)
    - Public & private messages :)
    - Three different quote types: "Blockquote", ">" quote and "XX>" quote
    - FidoNet support (I haven't tested it, it probably doesn't work) :O
    - File attachments to messages


4. Requirements
---------------

    - Linux operating system (atleast 2.0.32 will do). Currently
	  the developing is done on 2.2.13. Porting to other 
	  unix-resembling systems should be quite easy and you can 
	  freely do a port if you wish. Please consult me
      first, though. :) 

    - MySQL database server (atleast v3.21.33c works). Developing
	  is done on 3.22.25. MySQL is FREE for noncommercial use. 
	  At the time of writing this, it was available from "www.tcx.se".
	  Most of VMatik data handling is done by MySQL.
      
    - mgetty is required if you have modem lines. telnetd can be used
	  for telnet connections, but SSH should be used instead for
	  security. All of them are available freely from the net.
	  You can probably also use any other daemon which provides
	  shell connections.

    - KNOWLEDGE about running BBS systems and using Linux. 
      Understanding/writing C code and SQL will probably help, 
	  because there is no fancy interface for everything in VMatik.
	  

5. Installation
---------------

    1) You MUST install MySQL before trying to compile VMatik.

       [ MySQL daemon must be running all the time that VMatik
         is active (or could be activated) and also when VMatik events 
         are ran with crond. Aka "it should be running always". ;)
         Personally I have it in started in my /etc/rc.d/ files. ]

	2) Add user "bbs" and group "bbs" to your "/etc/passwd" and "/etc/group" 
       files, having "/home/bbs/vmatik" (the main executable) as the shell.
	   
	   [ Whenever any user uses the bbs, she must normally(!) first 
	     logon as "bbs",  so it probably should not have a password.
	     You might want to see chapter 13 about security issues.
       
         If you wish, you can hack the daemons automatically to login 
         as correct user on certain lines/devices, so the user has only 
         to type her VMatik-specific username and password. ]

    3) Set a global env variable $VMATIK to point to the home 
	   directory of the created user. (e.g. in "bash" add something 
       like "export VMATIK=/home/bbs" to "/etc/bashrc").

	4) Execute "./configure" in the main vmatik distribution dir.

	5) Edit "src/main/config.h" to suit your needs. Atleast change the
       SQL password!

	6) Execute "make", followed by "make install". 
       WARNING: "make install" WILL OVERWRITE your previous 
       vmatik configs/ and display/ files, if any.

       [ No errors or warning messages should be produced during the
	     compilation. ]

	7) Change dir into "sql_scripts/" and execute "./createdb". 
       It creates the necessary SQL tables and SQL user for 
	   vmatik.
	  
    6) Modify "configs/vmatik.cfg" in $VMATIK to suit your needs. The
       configuration file includes explanations. Remember to change
	   the Sysop's shell password! 

    7) Execute "utils/vmcfg". This compiles the "vmatik.cfg" to
       binary. You must do this every time you change vmatik.cfg

    8) Now you can try to login to the bbs as "new". First user
       gets Sysop access.

    9) Install mgetty and/or any other daemons you wish to provide
       the connections with.
		 
	   [ NOTE: No file transfer protocols are compiled by 
	     default! See dir "src/protocols/" and compile what
		 you need. ]


5.1 Upgrading from previous version
-----------------------------------
File 'ChangeLog' contains notes of what was changed, 
and what you'll have change, if anything.

WARNING: "make install" WILL OVERWRITE your previous vmatik 
configs/ and display/ files, if any.


6. BBS structure
----------------
Most of VMatik commands are executed from a single menu, the "main menu".
The user is simultaneously in some conference, and on some 
messagearea and some filearea, if such exist in that conference.

The benefit of this approach is that the user doesn't have to run
around from "file prompt" to "message prompt" etc, and try to remember 
which commands work where.

Here's a [confusing] picture of a possible situation =)
(* == user is here)

.------|Main prompt]-------------------------------
|
| Conference1-------.
|                   | Filearea 1 of conf 1
|                   | Bulletins of conf 1
|
|*Conference2-------.
                    | Filearea 1 of conf 2
                    |*Filearea 2 of conf 2
                    | Filearea 3 of conf 2 
                    |*Msgarea 1 of conf 2
                    | Msgarea 2 of conf 2
                    | Bulletins of conf 2
 

Note that global filearea commands and upload duplicate checking
recognize ONLY the fileareas in the current conference. So you
should put all fileareas having any similarity to same conference.
(e.g. you could put "PORN" areas to one conf, "WARE" to another <grin>)

Some conventions: 
    - The first conference is the "newuser conference". Make it include 
      whatever you wish to provide for new, unvalidated users. 
      Of course you can grant newuser whatever access if you wish.

    - Accesslevel 0 is for new users, 31 for the Big Boss #1.


7. BBS commands
---------------
The commands for end users are in the menu files, you can see
them with "?". Their functions should be self-explanatory. 


7.1 Filearea related
--------------------
There is one thing worth special attention, and that is the
"F" (list files) command and its parameters. You can take a look 
at them with giving "F" and then "?". After you've done that,
here's some examples:

"F 100-200,250"  : Display files from "100" to "200" and file "250".
"FG *phuck*"     : Display files having 'phuck' in the filename
                   from all areas
"F 'goat'"       : Display all files having 'goat' in the file description
"F since -5"     : Display all files that have been uploaded since 5 days.

Note that you can use these same arguments to Kill, VAlidate, TEst,
TRansform, MoVe, View, describe and globally list files. I think
it's a pretty powerful interface.

There's also following "global" commands for experienced users:

DG              : Download globally from all areas (in this conf)
*G              : Select files globally from all areas

Remember that using global commands with bad arguments
can cause disastrous results: e.g. You can accidentally 
select 59585 files to be downloaded.

Here's some commands that should be accessible by trusted people
(Sysops and Co-Sysops) only (shown with "?S"):

K               : Kill file(s)
MV              : Move file(s) from area/conf to another
VA              : Validate/unvalidate file(s)
TE              : Test file(s)
TEG             : Test file(s) globally
TO              : Touch file(s) [set upload date to current]
TR              : Transform file(s)
TRG             : Transform file(s) globally
W               : Describe file(s)      (W as in "Write")
WB              : Bulk describe file(s) (WB as in "Write Bulk")

AL              : Add a filearea to current conference
ML              : Change fileareas display location in the arealist

LU              : Locally Upload files to the current filearea
DUMP            : Modify timelimit of some user online according to node
USERLIST        : List all users in system
USERED          : The user editor

Additional file-command arguments for Sysops (not listed in help)

failed          : Files that have failed the integrity test
favorite        : Files marked as "Sysop Favorite"
nodesc          : Files that have no description
offline         : Files that do not exist on harddisk
online          : Files that are not offline
untested        : Files that have not been tested yet
untrans         : Files that have not been transformed yet
unval           : Unvalidated files

Select criterions can be catenated, for example: 
"W goat_??.zip 100- nodesc", would write descriptions to all
files from 100 to onwards, with names matching goat_??.zip 
and having no description.

The ASCII filelist is constructed of the following elements:

<number><flag><date><filename><description line 1>
                              <description line 2> etc
							                 
Others are trivial, but the flags are these

'v'		File is unvalidated. Someone with SECB_COSYSOP flag must
        validate it with "VA" before it can be seen or accessed
		by normal users. Files are as default unvalidated in a
		conference which has CONF_VALIDATE=Y in "vmatik.cfg".
'!'     File has failed integrity test (its "broken"), and has been
        in addition marked as FILE_FREEDL(!)
'o'     File is offline. Means that its in filelist, but not in
        the corresponding directory. Offline files are not seen
		by normal users. You can update the offline status of
		files using "utils/mark_offline"
'p'     File is marked as private. Currently this is not set by
        VMatik anywhere.
'+'     File is marked as "SysOp Favourite". Currently this is not
        set by VMatik anywhere.
		
Free download -files are not marked with a flag, because users have
a tendency to abuse them. :)


8. User/Sysop interaction
-------------------------

8.1. Peeking
------------
When user is online, you can check what she is doing by
executing "utils/vuohiv <node_number>" in a shell.
The last "v" in vuohiv stands for Voyeur, of course. 
["utils/vwho" lists from a shell who is online on what nodes]

Using vuohiv, you can type text to the user. You can
also execute commands, like toggle a chat mode. You can
get a command list by pressing "CTRL-b-h". The chat,
for example, is "CTRL-b-c". You can exit from the chat
by pressing ESCape.

"xterm" with black background is probably the best for using 
vuohiv... Atleast when user transforms files using SModem, 
"rxvt" gets a little silly.

A graphic X control panel for the whole system will be there
if somebody bothers to do it. At the moment I don't personally
feel too motivated. :( 


8.2 User yelling ("Requesting chat with SysOp")
-----------------------------------------------
In order to activate yelling command ("O") for users, 
"utils/yelld" must be ran. You can enter a TTY, file or a
device where the text output is directed, or specify a sample
to be played. Samples will just be written to "/dev/audio".

Yelld just lets you know that the user wants to talk.
You must run "utils/vuohiv" to do the actual chatting.


9. BBS directories
------------------

configs/        All config files
confs/          Conferences, their bulletins & msgareas here
data/           The static datafiles made by "vmcfg"
display/        Textfiles ("menues") shown to the user
docs/           VMatik documentation
doors/          External commands/games/etc, to be executed from the BBS
logfiles/       The logfiles made by VMatik
temp/           The upload temporary directory. Have HD space here!
users/          Users home directories
utils/          Utils which can be run from a shell

Directories can naturally be soft links pointing somewhere else.

Note that most dynamic data (like userdata and filedata) is kept 
in the MySQL database "vmatik". 

9.1 Additional distribution directories (not installed)

contrib/        Stuff with no direct connection to vmatik
obsolete/       Old utils which no longer work. Check for ideas!
src/            The source code
src/doors       Sources for door programs
src/main/       Sources for VMatik executable
src/lib/        Sources for door interface library
src/protocols/  Filetransfer protocols
src/utils/      Sources for external utilities
sql_scripts/    SQL scripts for database creation


10. Text control codes
----------------------

Action codes
  ~#PA             Pause (no text)
  ~#RE             Any key to resume (Pause)
  ~#NM             Turn more prompts off
  ~#MC[cmd]        Menu command
  ~#NC             Disable codes for the rest of the text
  ~#TF[file]       Show textfile
  ~#RA[file]|[max] Show random textfile (file is e.g. "/blaa/bloo/foo%d.bar",
                   %d is the generated random number [1,max]

String codes
  ~#RN             Real name
  ~#HA             Handle
  ~#OR             Organization
  ~#LO             Location
  ~#PH             Voice Phone
  ~#SL             Screen length
  ~#PR             Protocol ID
  ~#DA             Current date
  ~#ID             User serial ID number
  ~#DT             Daily Time
  ~#FC             User's FirstCall date
  ~#LC             User's LastCall date
  ~#OL             Online baud
  ~#SE             Security level
  ~#UB             Uploaded bytes
  ~#UF             Uploaded files
  ~#DB             Downloaded bytes
  ~#DF             Downloaded files
  ~#BA             Bytes avail
  ~#FA             Files avail
  ~#MP             Messages posted
  ~#TC             Total calls by user
  ~#CN             Name of the current conference
  ~#CU             Number of the current conference
 
Main prompt (in strings.XXX)

  ~~               Print ~ char
  ~A               Last msg read pointer
  ~C               Conference name
  ~E               Highest message
  ~F               Current fileareanumber
  ~L               Message base number
  ~M               Message base name
  ~N               Conference number
  ~T               Time left in minutes
  ~B               Node number
  ~S               BBS name

Execution of commands in vmatik.cfg

 %D == Name of the current TTY device
 %H == User's handle
 %N == Node number if any, else "*no"
 %O == User's organization
 %P == $VMATIK path
 %R == User's realname
 %S == User's seclevel
 %Z == User's zipcity


11. External stuff
------------------
In "utils/" there's all kind of useful shell executable stuff. 
Every util is documented at the beginning of its source code, 
check them out.

"doors/" has some stuff which is designed to be launched from
the system. Currently there's not many of them. Daydream doors
are probably rather easy to port.

I will someday document all of those here. But not now. =)


12. About the source code / theory of operation
-----------------------------------------------
If you're not interested in this topic, you can skip it. :O

VMatik is currently in a rather early stage. The main priority
has been given to make the basics work as they should. Finesse
and optimizations come afterwards. Unfortunately the same is true
for lots of error checking. The behavior might be bad in
situations I haven't foreseen or ran into. This is called
the "chaotic software development model". =)

VMatik development goes on and problems will be eventually
fixed because I'm personally interested in running a BBS. 
[Actually that's a lie. The truth is that I'm a sad nerd and have 
not much else to do. =)]

However, much depends on the feedback and the QUALITY of the feedback
I get from the people who try VMatik or decide to run a system
with it. If you have good ideas about HOW something could be better 
or done more efficiently (and not just "this and that sucks"), 
I'd be very interested to know. Also, I'd really appreciate it if 
there's anybody who would like to help me with developing VMatik 
by coding any of the functionalities that are still missing 
(see file TODO).

And now, after all that blaah-blaah, about the source itself:


12.1 In the beginning
---------------------
Before starting to make VMatik, I tried first to find a suitable
BBS software for my own use. I failed. Either the softwares had
completely wrong approaches, looked awful or didn't know a
word about bi-directional protocols or Ul:Dl ratios. There were 
even some which were coded in the proud language of 
"Uber alles Deutschland"... DayDream seemed to have atleast the basics,
and had a classic user interface liked by many (well ehm, 
I never was particularly fond of it), already known from 
AmiExpress and PCBoard.

The DayDream source (upon which VMatik is based) was unfortunately 
a monster (sorry Antti). Everything was hardcoded into it, 
all flags about different things were scattered around the source 
in 1L<<5 format, it was bursting with global variables,
nothing was commented, "-Wall" wasn't used (I got a SHITELOAD of 
warnings at first) and variables having nothing to do with 
fish were named "fish". :( The search method for everything 
was brute force linear search and fileareas were just ascii
files. It was horrible. :)

I have tried to change all those awful things, and kilotons 
of original DD code went straight to hell. ;) Flags are now
#defines with sensible names and variable names resemble their usage.

Because of quite heavy coupling (functions call each other a lot
across the .c file boundaries) I've given the functions a "??_" 
prefix to indicate their location in the source files. For example, 
"fl_*" means that the function is located in "filelist.c".
                                              ^   ^
There's still many functions left from DayDream which haven't 
yet been touched by me. Thus they don't yet follow the same naming 
conventions as the rest, and don't have commentation.

In time, I'll see if I can do anything about the global variables.


12.2 Use of SQL in VMatik
-------------------------
As stated before, most of the database handling stuff is
delegated to MySQL. That includes all data about
users, fileareas, files, flagged files, last read pointers,
filearea display orders and file backups... That is,
all data that is suspect to change at regular intervals.

Conferences and messageareas will be transported to MySQL 
in future from their current location in "vmatik.cfg".

The good thing about MySQL is that with suitable indexing
it can handle big databases efficiently (e.g. individual users 
and files can be found in a blitz) and provide almost 
the whole querying strength of SQL standard.

The bad thing is that with small systems the SQL queries
are an overhead (you can't probably notice the overhead,
but in aesthetical sense its there) compared to the size of the
handled database. When we want something from MySQL, we have 
every time to sprintf() a string like "SELECT user_lastcall FROM
vmatik_user WHERE user_id=3" and then send that to the
MySQL server as a message. The reply comes as a message too,
and as everything is in ASCII format in the reply, integers 
have to be atoi():ed and so forth. 

This way the source also starts quickly to look like a bunch of 
SQL queries. However, if in future we want VMatik to provide an
ability to be able to have the SAME user online multiple times
simultaneously, while still maintaining her credits correctly,
atleast some of the queries have to be made realtime, 
and can't be done just at the beginning and ending of a call. 
This probably requires thinking about concurrency control and 
table locking as well?

With little SQL knowledge and "mysql" util you can check and 
modify all the databases that VMatik uses. Required knowledge
can be obtained by reading mysql's "manual.txt"... :)

Also, you can add and edit VMatik data directly with "mysql",
using whatever methods SQL provides. Unfortunately MySQL doesn't 
support 'foreign keys' or integrity constraints... If you don't 
know what you're doing, you can harm the integrity of the database.
For example, deleting a filearea from "vmatik_fileareas" won't 
delete the files on it: they still exist unaccessible on the 
astral plane of neverland in "vmatik_filelist".

Remember that the table and column names are hardcoded
into VMatik sources, so you shouldn't rename or remove them! 
You can of course add your own columns and tables to provide external
utils with some additional knowledge about your system.


12.4 Theory of operation
------------------------

12.4.1 The simple model of the life cycle of VMatik executable
--------------------------------------------------------------
[main.c]
Every VMatik node starts as an individual program, loading
the static system configuration data (stuff that originates
from vmatik.cfg) to memory. Almost anything else 
in MySQL database is loaded later on demand.

On logon, user is asked about the displaymode after
which a logon banner (def. display/iso/banner.???) is
displayed. Then the user name and password will be
asked, or newuser procedure started.

The password goes through MD5 before comparison, because
only a crypted "hash value" is stored in the database.
If the password is ok, most of the user data will be loaded
to memory,  and some checking about timelimits is done.
"welcome.???" is displayed.

[enterbbs.c]
According to her settings, user may be displayed the
new files and messages since her last call. User is 
automatically joined to the conference and filearea
she was on her last logoff. If none, it will be the 
default settings.

[domenu.c]
After that, the user is in main menu, giving the commands 
she likes and roaming around the bbs. Program execution 
branches at this point.

Finally, user logoffs (or is thrown out) and some information
is stored back to the database. VMatik dies.


12.4.2 Some technical stuff which requires explaining
-----------------------------------------------------

Global commands
---------------
All global commands (newscans, global filelist, etc) work
by invisibly transferring the user from area/conf to another
and executing the required single-area function on each location.
When all locations are visited, the user is taken back to the
place where the command was originally executed. 

In global file newscan, only the areas having newer "area_newestfile"
than users "since statement" will be considered. This is because
MySQL doesn't provide efficient method for "date<date2" type of queries,
and making the precalcs (more on them later) takes too much time here.


Filelist related
----------------
The most complex functions in VMatik are probably fl_filelist()
and those related to it.

fl_filelist() is the general filelist browsing function. Among
other things, it gets given a pointer to "SystemFunctions" structure,
which includes display, maintenance, init and exit functions. Those
functions define what fl_filelist() actually does: How it displays the
files, what it does with them, and if init or exit functions have 
to be executed for the current action.

For example, moving files needs an initialization which
asks about the destination area, and an exit function which
sets the area_lasttouch pointers after all stuff has been
moved. There has also to be a maintenance function which
moves the actual files.

Also, fl_filelists gets an "orders" SQL string argument.
"orders" defines which files will be included in the
operation and its beforehand made from user arguments by 
fl_parseargs(). We don't expect the users to understand SQL, 
so a more simple and faster interface is provided.

The requirement to display and operate with filearea-specific
file numbers is the largest single overhead in VMatik.
To be able to display the same file numbers NOT depending on the
given search conditions requires an user/area specific 
precalc table. If the numbers were generated on the fly, 
you could get different filenumbers for same files with two 
different queries, and selecting those files would require
to use the exactly same search conditions. Without precalc,
for example "F suck*" would give you "1-10" if there were 
10 files beginning with "suck", but "* 1-10" afterwards could 
give you "abraham*" if the area was sorted in alphabetical order.

Thus the file number is always joined from the precalc_table
when a filelist query is made. Files not in the precalc table
are not included. By constructing the precalc tables from the 
filelist noting all the access stuff we can quietly rule
out all the files (private, unvalidated, etc) which the user
should not see without having to bother about them every time
we access the filelist. There will be no gaps in the numbering of 
the files for the user. Sorting is also done in the precalc phase.

In the start of fl_filelist(), a precalc making/checking
function is executed. If the precalc doesn't exist or
is older than filearea_lasttouch it will be re-made. 
Same will happen if user has changed the filearea sort 
order (that function zeroes the precalc_date).

All precalcs for current user will be deleted on logoff.
After all, they take quite a lot of hd space. [You should
always have lots of free space on the partition you have the
MySQL tables on].

Upload, Download and credit handling (Background checker)
---------------------------------------------------------
When starting an upload or download, we ALWAYS fork() the
background checker. It sits on the background and waits for
stuff to appear to a DSZ-format logfile. The log format is 
something like this:

S  29190     0 bps  981 cps   0 errors     0 1024 jenna022.jpg 0
H  58496     0 bps 1221 cps   0 errors     0 1024 deicide.zip  0
e  56981     0 bps 1282 cps   5 errors     0 1024 billybob.jpg 0
E  43856     0 bps 1531 cps   0 errors     0 1024 jenna044.jpg 0
S  37987     0 bps 1384 cps   0 errors     0 1024 jenna041.jpg 0

Where "S" cryptically means an upload, "H" or "s" a download,
"E" an upload error and "e" a download error (It might be "skip", 
for example). The second column from left is the file size, 
and the second from right the filename. I don't know how
filenames with spaces are handled. Such filenames are
abominations anyway. =)

You can NOT depend on the columns starting at the fixed locations.
The "bps", "cps" and "errors" strings may be different with 
different protocols, but the column amount, order and meaning
should always be the same. In addition, every line MUST end with '\n'.

Every transfer protocol used with VMatik MUST produce a DSZ logfile 
during their execution.

When bgchecker finds a new line in the logfile, it analyzes
its type, and then either 

a) Checks the uploaded file for FILE_ID.DIZ, tests its integrity 
   and transforms it, if possible. Then the file is added to the 
   filebase and credits may be given (depends on filearea/conf cfg)
b) Removes download credits from the user (if its not a freedl file,
   a freedl area, or a broken file), increases the file's download 
   counter, modifies its last download date and removes the file from 
   users flaglist.
c) Does nothing if the entry is invalid

After the transfer is complete, parent process signals 
bgchecker with SIGUSR1. That way bgchecker knows no more lines 
will appear to the logfile. It will process the lines that
are left, and commit suicide. :) BGChecker doesn't care if 
the user logoffs. If the user is online, it will send an OLM 
telling that its finished and the results of the transfer.

It will cause problems if the background checker isn't allowed to 
suicide naturally (e.g. if its killed with SIGKILL instead).


13. Security issues
-------------------

13.1. Providing a secure connection over the net
------------------------------------------------
Its really dangerous to provide telnet connections over the net.
Any machine on the way can snoop the passwords your users give,
and make a mess out of your system, and/or distribute the passwords
to the public. To prevent this, you should force your users
to use secure (crypted) connections.

A protocol called SSH can be used to provide secure service.
You can get ssh client and server for Linux from "www.ssh.fi" 
for free. SSH supports atleast DES, 3DES and Blowfish crypting.

Once you have compiled the package, just setup sshd and start
it to accept connections. Users can then login your site from
the net with "ssh -lbbs <your_address>". Remember to allow only 
those ciphers you consider safe (3DES, IDEA, Blowfish probably). 
Never allow cipher type "None" or "AnyCipher", or it can be
just as bad as telnet.

Zmodem can be used over an SSH connection with suitable
client software. On Win95, you can use a telnet replacement
called SecureCRT. Its also rumoured that TeraTermPro will do.
The files are then transferred in ordinary fashion.


BTW: As weird as it sounds, it has been said that it perhaps would 
be better to run a modern Kermit (not 1982 one) to transmit files 
with SSH. VMatik doesn't currently come with kermit protocol, but 
perhaps someone would add it? On Windoze, NT and OS/2, chech out 
software called "Kermit 95".


13.2. Security holes, anyone? 
-----------------------------
On RH6.1, if you do NOT list vmatik in /etc/shells, normal shell 
users can't do "su bbs" with a different shell than vmatik and 
thus abuse the bbs account priviledges. You can check that this
is so on your system by trying "su --shell=bash bbs" (after
you've changed bbs's shell to vmatik in etc/passwd, naturally)
on your system. If you get "bash", it has a security hole.

Password for vmatik MySQL databases is defined in "main/config.h"
and thus is readable from the compiled executable binaries. 
So make sure that no-one with shell account can access vmatik
binaries. This can (for example) be done by just chmod:ing the 
bbs:bbs owned bbs home directory to o-rwx and making sure no 
non-root users have bbs group access.


14. Reporting bugs/new ideas
----------------------------
See files "TODO", "BUGS" and "docs/faq.doc" first!!!

When you report bugs, you SHOULD try to trace the problem first
by yourself by adding traps (string outputting? =) to the source,
and finding out whats wrong. In addition to stating the
problem and the cause, I'd greatly appreciate if you'd 
outline the main points of the solution for me as well. diffs rule!

I understand that this is not always possible, due to lack of
skill in programming or because not simply interested enough. 
If you email me the problem and just the info about your computer
and system config, I may be unable to do anything about it. 

But keeps those bug reports coming anyway. ;)


15. Author / Email
------------------
Igor Wronsky (aka ~g/RRR) is a seasoned bulletin board system operator
with over six years of field experience. His freetime hobbies include
gardening and goat herding...

At the moment you can reach him at <iwronsky@yahoo.com>

What a lame address. :)

My PGP public key resides in "docs/wronsky.pgp.asc". 


16. Acknowledgements and the HALL OF FAME
-----------------------------------------

 o VMatik is based on DayDream BBS software by Antti "Hydra" Hyrinen.

 o Thanks to MySQL authors. Hours and hours were used to ruminate 
   on suitable data structures, sort routines, search algorithms,
   indexes and such, before I decided to dump it all and use MySQL.

 o And at last, but certainly not least, I'd like to express my
   endless gratitude to My Little Pony 'n Friends! (You know,
   them pinkish quadrupeds).


17. Glossary
------------

"Vuohi" is a finnish word for a particularly noble and godly creature.
The name "VuohiMatik" is a tribute to the "kala" variables of DayDream.


