   #####                                              #####    ####   #####
  ##   ##                                            ##   ## ##   ## ##   ##
  ##                                                 ##   ## ##   ## ##
   #####   #####   ##   ## ## ###   #####  # ####    ######  ######   #####
       ## ##   ##  ##   ## ##   ## ##   ## ###  ##   ##   ## ##   ##      ##
  ##   ## ##   ##  ##   ## ##      ##   ## ##   ##   ##   ## ##   ## ##   ##
   #####   ##### #  #####  ##       #####  ##   ##    #####   #####   #####
 
                   B U L L E T I N  B O A R D  S Y S T E M
                    Copyright (C)Simon Horton 1998 - 2008


INTRODUCTION

Sauron Linux BBS is a multi-user configurable script file driven bulletin board system, 
which can be almost set up anyway you want it.

 - Almost completely script driven.
 - Have as many sub-boards as you want.
 - Support for all download/uploads protocols
     -X/Y/Z MODEM
 - Door system using dorinfo0.def
 - Multi Guest accounts
 - Multiple message forums
    - Full ANSI Editor
 - Multiple File Areas
    - Main and Sub file areas
    - CD-ROM support using files.bbs
    - OPEN/CLOSE file areas
    - FTP Style file areas
 - Internal mail system.
 - Uses internal Linux user authentication.
    - 9 User Access levels
    - Call and Time restrictions
 - Multiple nodes
 - Telnet, SSH access
 - Ncurses Sysop management tool.

As this software is still in development, and as of yet, no stable release.
We cannot guarantee that this software will to be without faults or bugs, but 
hopefully these should be few and far between.!

The current version is the result of a 2 year programming frenzy between 1998 -
2000 to convert Sauron DOS to Linux before all development ceased. This version
is the continued development over the last 6 months on bug fixes and 
enhancement.

Daily builds are available on the Sauron Support BBS.

SYSTEM REQUIREMENTS

Any Linux distribution, internet connection, 256 MB min..

CONTACT

I'm happy to answer any questions or help with any aspect of setting up your BBS, 
or fix any problems. 

Help is available at the following:

Email : support@sauron.org.uk
Web   : www.sauron.org.uk
      : www.sauron.uklinux.net

Via the Sauron Linux Support BBS via the forums, documentation:

BBS      : telnet://sbbs.ath.cx
Login    : guest 
Password : guestlogin

UPGRADING

If you are upgrading from a previous version of Sauron Linux then
please read the UPGRADE-<version>.txt file.

INSTALLATION

Installation from source will require the following prerequisites:

 - FreePascal version 2.2.0 www.freepascal.org
 - FPC Free Componate Library (FCL) for compiling SMT
 - Make
 - ldd
 
From within the upacked source directory, run the following which will
compile the source and install to /usr/local/sauron

(As root)
# make && make install          (Main BBS Program Files)
# cd smt                          
# make && make install          (Sysop Management Tool)
# cd ../sadduser
# make && make install          (Sauron Add User Utility)
# cd ../scripts
# make install                  (BBS Program Scripts)
# cd ../bbs
# make                          (DEMO BBS Files, Scripts, Menus, etc)

The following directories will have been created as part the installation:

/usr/local/sauron/bin	        - Main sauron program files (sbbs, smt)
/usr/local/sauron/data          - Database files
/usr/local/sauron/door          - Door programs
/usr/local/sauron/downloads     - Download file store (this can be anywhere)
/usr/local/sauron/files         - File Area data files
/usr/local/sauron/home          - User home directories
/usr/local/sauron/log           - Log files
/usr/local/sauron/mail          - Internal mail system mail files & messges
/usr/local/sauron/message       - Internal message files & messages 
/usr/local/sauron/newuser       - New user database file used by sadduser
/usr/local/sauron/newuser/skel  - Files to be copied to the user home directory
/usr/local/sauron/node          - Multi-user node lock files
/usr/local/sauron/script        - Script files
/usr/local/sauron/menu          - Menu Screens
/usr/local/sauron/temp          - Temp files
/usr/local/sauron/text          - Text files
/usr/local/sauron/sys           - System files
/usr/local/sauron/upload        - Temp upload area

BBS CONFIGURATION & SETUP

In order for the BBS to operate correctly a BBS user group and two Linux users 
need to be created; one user as the main Sysop user and the other as a Guest user 
if you want to run a guest system.

The following instructions assume the Linux distribution is either RHEL 4.x or 
CentOS 4.x. Usernames, Group Names and UID's can be changed to suit your own
requirements.

You will need to be the root user in order to install from the source
directory.

** NOTE **********************************************************************

Permissions and Group settings are important on the files and
directories, so please ensure that you following the instructions carefully as
having these incorrect will cause Sauron not to operate correctly.

*******************************************************************************

Creating a BBS group:
---------------------
By default the BBS uses the Group: BBS and Group UID: 700, this can be changed in 
linux.ini

groupadd -g 700 BBS


Creating Sysop & Guest
----------------------
By default the BBS uses user UIDs from 2000 in order to separate BBS users from normal
system users, this can be changed in linux.ini.

NOTE: The first BBS user must start from 2001 and not 2000, and it is recommanded that
main Sysop user be the first user.

useradd -n -m -k /usr/local/sauron/newuser/skel \
-d /usr/loca/sauron/home/sysop -s /usr/local/sauron/bin/sauron.sh \
-u 2001 -g 700 sysop

useradd -n -m -k /usr/local/sauron/newuser/skel \
-d /usr/loca/sauron/home/guest -s /usr/local/sauron/bin/sauron.sh \
-u 2002 -g 700 guest

copy .hushlogin from /usr/local/sauron/newuser/skel/ to each users home directory.
This will stop any system messages being displayed when the user logs in. When using
the Sadduser utility to add a user, this file will be automatically copied during the 
user creation process.

Create a password for each user.

Permissons and Ownership
------------------------
Permissions need to be set on all Sauron BBS files and directories to SYSOP:BBS.

chown -R sysop:bbs /usr/local/sauron

The following permissions should have been set as part of the build, and may not
need to be applied.

chmod 777 /usr/local/sauron/bin
chmod 777 /usr/local/sauron/data
chmod 777 /usr/local/sauron/door          
chmod 777 /usr/local/sauron/downloads     
chmod 777 /usr/local/sauron/files         
chmod 777 /usr/local/sauron/home          
chmod 777 /usr/local/sauron/log           
chmod 777 /usr/local/sauron/mail          
chmod 777 /usr/local/sauron/message       
chmod 777 /usr/local/sauron/newuser       
chmod 777 /usr/local/sauron/newuser/skel  
chmod 777 /usr/local/sauron/node          
chmod 777 /usr/local/sauron/script        
chmod 777 /usr/local/sauron/menu          
chmod 777 /usr/local/sauron/temp          
chmod 777 /usr/local/sauron/text          
chmod 777 /usr/local/sauron/sys           
chmod 777 /usr/local/sauron/upload        

chmod 777 /usr/local/sauron/bin/sbbs
chmod 777 /usr/local/sauron/bin/sauron.sh
chmod 777 /usr/local/sauron/bin/smt
chmod 777 /usr/local/sauron/bin/sadduser
chmod 777 /usr/local/sauron/bin/createuser

chmod 666 /usr/local/sauron/bin/linux.ini
chmod 666 /usr/local/sauron/bin/sadduser.ini
chmod 666 /usr/local/sauron/data/*
chmod 666 /usr/local/sauron/text/*
chmod 666 /usr/local/sauron/sys/*
chmod 666 /usr/local/sauron/script/*

Linux.ini configuration file
----------------------------
The linux.ini file contains all the BBS configuration information required
by the BBS to operate correctly. We only need to change a few sections as part
of the setup. There are descriptions for each entry in the INI file, so 
modifying the file should be relativity easy.

Sysop User Linux UID needs to changed to the UID of the main Sysop user.

SYSOP=2001

Guest user Linux UID needs to be changed to the UID of the Guest user.

GUESTUID=2002

Sauron directories will need to change if the default installation area has been
modified.

Sadduser.ini
------------

BBS group GID

USERGRP=700

BBS User UID base

USER=2000

Testing the BBS
---------------
Login in from a console as the Sysop user should display this screen:

ANSI detected....

CLIENT HOST: 1207575603
   BBS NAME: Sauron Linux BBS
       HOST: sbbs.ath.cx
       DATE: Monday 7 Apr 2008, 2:40pm
       NODE: ( 1 of 5 )

         <linux.logo>

[PAUSED] Press [C] to continue


Main Files
----------

/usr/local/sauron/bin/sbbs         - The core BBS program
/usr/local/sauron/bin/linux.ini    - BBS configuration file
/usr/local/sauron/bin/sadduser     - Sauron Add User utility
/usr/local/sauron/bin/sadduser.ini - Sadduser configuration file
/usr/local/sauron/bin/createuser   - Utility to create a user userinfo.dat file
/usr/local/sauron/bin/sauron.sh    - BBS user shell
/usr/local/sauron/bin/smt          - Sysop Management Tool

/usr/local/sauron/sys/banned.txt   - List of usernames on allowed on the BBS
/usr/local/sauron/sys/idle.txt     - Message displayed when the user is logged out
                                   - after defined idle time
/usr/local/sauron/sys/quote.txt    - Single line quotes displayed on a menu script
                                   - using the quote command
/usr/local/sauron/sys/timeup.txt   - Message displayed when the user runs out of online time

/usr/local/sauron/data/area.<1>    - File area configuration file. <1> is the file area number
                                   - file area 1 : area.1
/usr/local/sauron/data/areas.dat   - List of all file areas
/usr/local/sauron/data/login.dat   - Stores the last 5 logins
/usr/local/sauron/data/message.dat - List of all forum areas
/usr/local/sauron/data/msindex.dat - Forum post numbers
/usr/local/sauron/data/simpbbs.dat - Legacy BBS file from Sauron DOS (to be removed)


USERS

Sauron Linux BBS uses normal Linux user accounts and groups with the only difference is that BBS
users run sauron.sh at login instead of for bash for example, which in turn calls the 
main BBS binary.

User Creation
-------------
BBS users can be created in one of three ways: 

1. Use the standard Linux tools ensuring that each user's main group is the BBS group and that 
their logon shell is set to sauron.sh. Also to stop system messages being displayed when the 
user logs in, either add .hushlogin to /etc/skel or create the file in their home directory. 
(see example in installation)

2. Using Sadduser to automaticaly add users who have signed up via the BBS. Please read
sadduser.txt in the docs/ directory for more information on using and setting up Sadduser.

3. Use the Sysop Add User page in the BBS, this method also uses the Sadduser utility to create 
the user.

By default users home directories are in /usr/local/sauron/home, if this changed, the HOMEDIR entry
in linux.ini and sadduser.ini will need to be modified to point to the new home path.

userinfo.data
-------------
Each user will have a userinfo.data file residing in their home directory. This file contains all
data relating to the user, such as, UID, full name, login times, call dates, call times etc.

This file is automatically created either by the Sadduser utility as part of user creation process,
or by the Createuser utility called by sauron.sh if the file cannot be found during login.

Guests Users
------------
A BBS Guest user account is also a normal BBS user account with a slight difference, the connecting
hostname is used to identify the user and their username will be prefixed with a number between 
1 - 999. This allows a guest user (as long as they're connecting from the same host) to personlise 
their guest account, and for the BBS to monitor call times.

A guest userinfo.data file in the guest home directory will be prefixed with the connecting hostname.

eg: userinfo.data.<hostname> userinfo.data.sbbs.ath.cx

The guest username number prefix is set in the linux.ini file, and will be incremented as each new
guest account is created. When the guest numbering will revert back to 1 when it reaches 999 and start 
to recycle old accounts.

User Time
---------
Sauron BBS can operate a call and time allowance over a 24 hour period, which can be
easily set per user level within linux.ini

For example, if a user connects to the bbs at 15:50 14 March and they have not connected
in the last 24 hours, their defined time/call allowance will not be reset until 24 hours
later on the 15:50 15 March.

If you wish to operate a time/call allowance system, then see the example logon.sfi script
on how to set this up and linux.ini.

User Management
---------------
The Sysop Management Tool (SMT) can be used to manage user data.

MULTI-NODE BBS



File Repositories
-----------------

Downloading Files
-----------------

download.sh
-----------

Uploading Files
---------------

upload.sh
---------

FTP style file repositories
---------------------------

directory.info

Messaging Forums
----------------


BBS Mail
--------


Sauron System variables
=======================

Variables that are used in menu files must be in CAPITAILS.
Can be used in the PRINT command

Linux System
============

Colours
=======
Sends ANSI colour codes.
Can be used in Menus, the PRINT or YESNO command, or text files using PRINTFILE.

Example:
--------

print "f:yellow%Welcome to our BBS%f:green% %username%"

NOTE: These can be used instead of the Sauron Colour Codes

%F:BLACK%		-    Forground Black
%F:RED%		        -    Forground Red
%F:Green%		-    Forground Green
%F:YELLOW%		-    Forground Yellow
%F:BLUE%		-    Forground Blue
%F:MEGENTA%	 	-    Forground Magenta
%F:CYAN%		-    Forground Cyan
%F:WHITE%		-    Forground White

%B:BLACK%		-    Background Black
%B:RED%		        -    Background Red
%B:Green%		-    Background Green
%B:YELLOW%		-    Background Yellow
%B:BLUE%		-    Background Blue
%B:MEGENTA%	 	-    Background Magenta
%B:CYAN%		-    Background Cyan
%B:WHITE%		-    Background WhiteAs this software is still in development, and as of yet, no stable release.
We cannot guarantee your time here to be without fault or bugs, but hopefully these
should be few and far between.!

The current version is the result of a 2 year programming frenzy between 1998 -
2000 to convert Sauron DOS to Linux before all development ceased. This version
is the continued development over the last 6 months on bug fixes and 
enhancement..



Directories
===========

%SYSTEMDIR%       -   System Directory
%SCRIPTDIR%       -   Script File Directory
%BBSMAILDIR%      -   Mail Directory
%MENUDIR%         -   Ansi & Avatar Menu Screens Directory
%MSGDIR%          -   Message Directory
%TEMPDIR%         -   Temp Directory
%BINDIR%	  -   Binary Directory
%TEXTDIR%	  -   Text Direcotry


User Variables
==============
                   
%CALLSLIMIT%	  -   Users number of Calls allowed per day
%TIMELIMIT%	  -   User daily time allowance
%SESSIONRESET%    -   Date and Time the users 24 hr session resets

%USERCREATION%    -   Date and time of user account creation
                  -   Format: dd/mm/yy-h:m:s

%NEWUSERNAME%     -   User Name entered using JOINUSERNAME command
%USERNAME%        -   User Name
%USERFULLNAME%    -   User Full Name
%USERTOWN%        -   Calling Location
%USERPASSWORD%    -   Password
%USERNUMBER%      -   User Logon Number
%USERTOTALCALLS%  -   Total User Calls To The System
%USERLASTCALL%    -   Last Call Date
%USERCALLSTODAY%  -   Total User Calls To The System during the last 24 hours
%TIMELEFT%        -   Current User Time Remaining
%TIMEONLINE%      -   Current User Time Online
%CALLSWHILEAWAY%  -   Calls To System Since Last User Logon
%MAILCOUNT%       -   Number Of Emails User Has
%USERDOWNLOADS%   -   Total User Downloads 
%USERDLBYTES%     -   Total User Downloads Bytes
%SCREEN%          -   User Screen Type Ansi or Avatar
%COLOUR%          -   User Colour ON or OFF
%BULLETINNUMBER%  -   User Bulletin Number
%USERINFO1%       -   Displays Entered User Info
%USERINFO2%       -   Displays Entered User Info
%USERINFO3%       -   Displays Entered User Info
%USERINFO4%       -   Displays Entered User Info
%USERINFO5%       -   Displays Entered User Info
%USERINFO6%       -   Displays Entered User Info
%USERINFO7%       -   Displays Entered User Info
%USERINFO8%       -   Displays Entered User Info
%EMSGWAITING%	  -   Does the user have mail in /usr/local/sauron/mail
                  -   Displays [YOU HAVE A MESSAGE]
%MAILWAITING%	  -   Does the user have mail in /var/spool/mail/<user>
		  -   Displays [YOU HAVE MAIL]

%INTERNETADDRESS% -   Displays users email address user@domainname
		  -   or user@localhostname

Misc
====
%BBSNAME%	  -   Name of the BBS ( Set in linux.ini - BBSNAME= )
%BBSHOST%         -   Hostname of the BBS ( Set in linux.ini - BBSTEL= )

%TODAYSDATE%      -   BBS current date/time

%IDLETIME%        -   BBS Idle time ( Set in linux.ini - IDLETIME= )

%NODE%            -   BBS node number of connecting host
%NODES%           -   Number of concurrent nodes allowed ( set in linux.ini - NODES= )


%TODAYSDATE%      -   Displays Todays Date
%CALLNUMBER%      -   Current Call Number
%LASTCALLER%      -   Displays Last Caller
%LASTTOWN%        -   Displays Last Callers Location
%IDLETIME%        -   Set idle time
 
%REMOTEHOST%      -   Display connecting hostname 
%REMOTEIP%        -   Display connecting host IP address

If connecting to the BBS via the console, then %remotehost% %remoteip% will be
set as the julien date/time stamp of the connection. 

%SYSOPUID%        -   Sysop Linux User UID (set in linux.ini - SYSOP= )
%GUESTUID%        -   Guest Linux User UID (set in linux.ini - GUESTUID = )

		 

Modem
=====

%PORT%             -  Modem Port Number
%BAUD%             -  Current BaudRate 
%LINEBAUD%         -  Line Speed
%CONNECTSTRING%    -  Modem Connect String

File 
====

%MAINFILEAREA%     - Displays Name Of Current Selected Main File Area
%FILEAREA%         - Displays Name Of Current Selected Sub File Area
%FILENAME%         - Dir/Name Of File Selected For Current Download or List
%FILECOUNT%        - Number Of Files In Selected Sub File Area

Forums
======

%MESSAGEAREA%    - Current Forum Area
%MESSAGESIZE%	 - Number of posts in the current forum

Sauron IF Conditional 
=====================

SEE SCRIPT FILES FOR EXAMPLES OF <IF>

IF <exp1> expression <exp2> command <exp3>

Expression usage: =, >, <, <>
Command usage: THEN,  EXECUTE, PRINT

Variables allowed in <exp1> :

%REGISTERED%       - True if a guest user has requested a BBS account.
                   - this is set by the command CREATEACCOUNT as part
                   - of the signup process.
                   - if %registered% = %true% then NOSIGNUP

%MAXCALLS%         - True if user has exceeded their call allowance
                   - if %maxcalls% = %true% then BYE

%MAXTIME%          - True if user has exceeded their time allowance
                   - if %maxcalls% = %false% execute ok.sfi

%MAXNODES%         - True if maximum concurrent connections have been reached
                   - reads node lock files in /usr/local/sauron/node

%MAXGUESTS%	   - True if the maximum concurrent guest connections has been reached
                    - reads node lock files in /usr/local/sauron/node

%ANSIDETECT%       - True if BBS detected a ANSI compatible terminal client

%ANSI%             - True if the user is using ANSI

%ERROR%            - Script commands/Shell set this to true if any error occurs whilst
                   - running. 

%YN% 		   - Set by the yesno command - Yes = true No = false

%BULLETINNUMBER%   - Current bulletin number

%USERBULLETIN%     - User Bulletin Number

%MAILCOUNT%        - True if user has mail in /usr/local/sauron/mail

%USERNUMBER%       - * not used * for linux version

%LINEBAUD%         - * not used * for linux version

%CALLSWHILEAWAY%   - Calls to the BBS while the user was away

%GUEST% 	   - True if Linux user UID = GUESTUID in linux.ini

%SYSOP%            - True if Linux user UID = SYSOP in linux.ini 

%USERLEVEL%        - User Level Number 1 - 9
                   - if %userlevel% = 3 execute levelthree.sfi

%FIRSTCALL%        - True if users first call to the BBS

%INTERNETMAIL%     - True if user has main in /var/spool/mail

Vars allowed in <exp2> :

%ERROR% 
%YN% 
%BULLETINNUMBER% 
%USERBULLETIN% 
%MAILCOUNT% 
%TRUE% 
%FALSE%

Example 1:
----------

if %guest% = %true% execute guest.sfi
execute main.sfi
[end]

There must be Guest UID defined in linux.ini in order to use %guest%

Example 2:
----------

if %sysop% = %false% then CONT
promptquotesoff
yesno "%f:white%Hello SYSOP, would you like to go the sysop menu? (Y/N) "
if %yn% = %true% then execute sysop.sfi
:CONT
execute main.sfi
[end]

There must be a Sysop UID defined in linux.ini n order to use %sysop%

Script Commands
===============


[text] = Optional
<text> = Required
---------------------------------------------------------------------------------

NAME
     REM [text] or ; [text]   

SYNOPSIS
     REM Copyright (C) Simon Horton
     ; Script comment

ERRORS
     NONE

DESCRIPTION
     Add a REM statment or comment in script files

---------------------------------------------------------------------------------

NAME
     LOCKUSER

SYNOPSIS
     LOCKUSER

ERRORS
     Set %error% to true if the same user/host is already locked on another node
     Errors logged to error.log

DESCRIPTION
     Creates a user lock file in /usr/local/sauron/node/<username>.lock
     or <hostip>.lock for guest users.

     eg:

     lockuser
     if %error% = %true% then NODELOCKED
     execute main.sfi
     :NODELOCKED
     print "The user (%username%) or host (%remotehost%) is already logged in on another node"
     logoff

---------------------------------------------------------------------------------

NAME
     DELETELOCKUSER

SYNOPSIS
     DELETELOCKUSER

ERRORS
     Errors logged into error.log

DESCRIPTION
     Deletes the users lockfile in /usr/local/sauron/node

     eg:

     yesno "Are you sure you want to leave the BBS (y/n) : "
     if %yn% = %false% execute main.sfi
     deletelockuser
     print "Bye, bye..."
     logoff

---------------------------------------------------------------------------------

NAME
     PRINTFILE <file>         

SYNOPSIS
     PrintFile /usr/local/sauron/text/welcome.ans

ERRORS
     %ERROR% set to true if file error
     Error logged to error.log
NAME
     SELECTMAINFILEAREA   

SYNOPSIS
     SELECTMAINFILEAREA

ERRORS
     NONE

DESCRIPTION
     Display lists of available file areas. Selected file area is stored in
     %mainfilearea%

     eg:

     [begin]
        s, 1, selectmainfilearea
     [end]

---------------------------------------------------------------------------------

DESCRIPTION
     Prints a Text, ANSI file. Files can contain sauron
     colour codes.

     Can also use system variables, eg:

     printfile %textdir%welcome.ans
     printfile %tempdir%/users%username%.txt

---------------------------------------------------------------------------------

NAME
     PRINT [text] with CR

SYNOPSIS
     Print "Welcome %username% To BBS"

ERRORS
     NONE

DESCRIPTION
     Prints text with a carridge return. Text can contain
     system variables, ANSI squences and Sauron colour codes.

     eg:

     print "%f:yellow%Todays date is%f:red% %todaysdate%"
     print "[[33mHello Guest.."

---------------------------------------------------------------------------------

NAME
     PRINTS [text] with no CR

SYNOPSIS
     Prints "Welcome %username% To BBS"

ERRORS
     NONE

DESCRIPTION
     Prints text with no carridge return so any addtional
     print command will add text to the end.

     Text can contain system variables, ANSI squences and 
     Sauron colour codes.

     eg:

     prints "%f:yellow%Welcome "
     print "[[33mGuest.."

     Output : Welcome Guest

---------------------------------------------------------------------------------

NAME
     PRINTTOLOG '<text>'        

SYNOPSIS
     PrintToLog "user %username% logged off" 

ERRORS
     %ERROR% true if any error writing to the log file

DESCRIPTION
     Logs information to the user log file, can have system variables

     eg:

     printtolog 'Logon=%username% Node=%node% Date=%TodaysDate%'

---------------------------------------------------------------------------------

NAME
     JUMP <label>             

SYNOPSIS
     JUMP NEWUSER

ERRORS
    Display on screen error if label is not found.

DESCRIPTION
    Jump to a label within the script file, all labels must be in CAPITALS
    
    eg:

    jump NOW
    <script ignored>
    :NOW
    execute main.sfi

---------------------------------------------------------------------------------

NAME
     :<label>                 

SYNOPSIS
     :LABEL

ERRORS
     Display on screen error if label is not found.

DESCRIPTION
     Label for JUMP & THEN Command, all labels must be in CAPIALS

     eg:

     if %error% = %true% then ERROR
     execute ok.sfi
     :ERROR
     execute error.sfi

---------------------------------------------------------------------------------
NAME
     PROMPT <text>         

SYNOPSIS   
     Prompt Command�[�A�B�C�D�E�F�G�E��] :

ERRORS
     NONE

DESCRIPTION 
     Sets up the prompt for script file menu. Can include colour codes 
     or system variables. If the prompt command is not set up as part 
     of a menu script, the default will be used.

     Default Prompt: --->

     eg:

     Prompt %f:red%Select Menu Option : %f:red%

     [begin]
       ; Start           Command Mode Of Script File
       ;  Key        Level           Command
       d,          1,            execute door.sfi
     [end]

---------------------------------------------------------------------------------
NAME
     PROMPTQUOTESOFF
     PROMPTQUOTESON

SYNOPSIS   
     As above

ERRORS
     NONE

DESCRIPTION
     If set to ON the input prompt will display a box round
     the cursor to length of the preset buffer.

     In order for the display box to be apparent, a background
     colour has to be set at the end of the command.

     eg:

     promptquoteson
     yesno "Would you like to send mail ? Y/N : %b:blue%"
     promptquotesoff

     eg:

     promptquoteson
     askusername "Would you like to send mail ? Y/N : %b:blue%"
     promptquotesoff
      

---------------------------------------------------------------------------------
NAME
     MENU                     

SYNOPSIS   
     MENU

ERRORS
     Logs error into error.log

DESCRIPTION
     Displays screen menu associated with script file.
     
     Running a script file called HELLO.SFI would use HELLO.ANS

---------------------------------------------------------------------------------
NAME
     CLS                      

SYNOPSIS   
     CLSE

ERRORS
     NONE

DESCRIPTION
     Sends screen clear codes to user terminal

---------------------------------------------------------------------------------

NAME
     EMAIL [USERNAME] or [UID] 

SYNOPSIS
     EMAIL
     EMAIL sysop 
     EMAIL %sysop%
     EMAIL 2003

ERRORS
     NONE

DESCRIPTION
     Send a BBS mail to a user

     If the username or user UID is opmited, the user will have to enter
     either another users name or UID.

---------------------------------------------------------------------------------

NAME
     READMAIL

SYNOPSIS
     READMAIL

ERRORS
     Will display 'Mailbox Empty' if no mail is found

DESCRIPTION
     Read BBS mail

---------------------------------------------------------------------------------

NAME
     EDITMAIL

SYNOPSIS
     EDITMAIL 
 
ERRORS
     NONE   
     
DESCRIPTION
     Allows a user to edit any BBS mail they have sent.

---------------------------------------------------------------------------------

NAME
     PAUSE

SYNOPSIS
     PAUSE

ERRORS
     NONE

DESCRIPTION
     Pauses script and waits for C to be pressed.
     Pause output is defined in linux.ini under PAUSEPAGE=

     eg:
     
      printfile %textdir%welcome.ans
      pause   

---------------------------------------------------------------------------------

NAME
    WHOSBEENONLINE

SYNOPSIS
    WHOSBEENONLINE

ERRORS
    NONE

DESCRIPTION
    Displays the last five users who have logged on the BBS

    uses data file: data/login.dat

    Also see: ADDTOLOGINLIST

---------------------------------------------------------------------------------

NAME
     WHOSONLINE

SYNOPSIS
     WHOSONLINE

ERRORS
     NONE

DESCRIPTION
     Displays list of users who are currently logged on and available nodes.

     eg:
     
      print "Who's online @ %bbsname%"
      print
      whosonline
      pause

      Reads node lock files in: node/*.lock

      Configuration optins in linux.ini:

      [MISC]
      ; 0 = Disabled 1 = IP Address 2 = Current Script Title
      SHOWWHO=2 

---------------------------------------------------------------------------------

NAME 
    ADDTOLOGINLIST

SYNOPSIS
    ADDTOLOGINLIST

ERRORS
    NONE

DESCRIPTION
    Records the user logins to dat/login.dat

    Recommand adding command into LOGON.SFI for normal users, and after registration
    of new Guest accounts. See guestlogin.sfi 

    eg:

    printtolog "User %username% has logged on"
    addtologinlist

    If you did not want to record sysop access..

    ; if sysop do not record logon
    if %sysop% = %true% then SYSOP
    ; not sysop so add to login list
    addtologinlist
    :SYSOP
    execute main.sfi
    [end]

---------------------------------------------------------------------------------

NAME 
     SCRIPTTITLE <TEXT>

SYNOPSIS
     SCRIPTTITLE Main Menu

ERRORS
     NONE

DESCRIPTION
     Sets a title for the current running script which is used in the
     WHOSONLINE command using option 2, or can be displayed on screen using the
     system variable %SCRIPTTITLE% in ANSI menus or script.

     eg:

     ; Set title
     scripttitle Playing Pimp Wars..
    
     doorcom /usr/local/sauron/doors/pimp.sh %node%

---------------------------------------------------------------------------------

NAME
     EXECUTE <script file>    

SYNOPSIS
     EXECUTE newuser.sfi

ERRORS
     BBS will halt if an error occurs

DESCRIPTION
     Call or start a script file
  
     eg:

      print "Welcome to our BBS..."
      print
      pause
      execute main.sfi

---------------------------------------------------------------------------------

NAME
     RETURN

SYNOPSIS
     RETURN

ERRORS
     NONE

DESCRIPTION
     Returns to the previous script file executed.

     eg:
      
     yesno "Are you sure you want to leave the BBS (y/n) : "
     if %yesno% = %true% then BYE
     return

---------------------------------------------------------------------------------

NAME
     LOGOFF                   

SYNOPSIS
     LOGOFF

ERRORS
     NONE

DESCRIPTION
     Logs user off system and closes connection:

     eg:
      
     print "Thanks for calling..."
     deletelockuser
     logoff

---------------------------------------------------------------------------------

NAME
     SHOWTIMELEFT             

SYNOPSIS
     SHOWTIMELEFT             

ERRORS
     NONE

DESCRIPTION
     Displays users time left in a menu system script. Can only be used if script is
     running as menu.

     Output is defined in linux.ini

     eg:

     showtimeleft

     [begin]
     ; Start           Command Mode Of Script File
     ;  Key        Level           Command
         d,          1,            execute door.sfi
     [end]

---------------------------------------------------------------------------------

NAME
     WAIT <length>            

SYNOPSIS
     WAIT 10

ERRORS
     NONE

DESCRIPTION
     Pauses script for xx seconds.

---------------------------------------------------------------------------------

NAME
     SETCURSOR <X> <Y> 

SYNOPSIS
     SETCURSOR 10 10

ERRORS
     NONE

DESCRIPTION
     Move cursor to screen posistion X Y
     Only works on ANSI terminals

---------------------------------------------------------------------------------

NAME
     DIRECTORYLIST <path>

SYNOPSIS
     DIRECTORYLIST /usr/local/sauron/downloads

ERRORS
     Logs errors into error.log
        
DESCRIPTION
     An FTP style file lister, viewer and downloader. Can be used in an normal
     script or as part of a menu script.

     Path can contain system variables.

     Note:

     fileviewer & downloadscript must be set prior to calling
     directorylist.
	
     Create the text file directory.info in the target path for an area
     description.

     eg:

     fileverviewer /bin/vim       ( See command detail for more informtion)
     downloadscript download.sfi  ( See command detail for more informtion)
     directorylist %filesdir%

     eg:

     fileverviewer /bin/vim       ( See command detail for more informtion)
     downloadscript download.sfi  ( See command detail for more informtion)

     [begin]
       d, 9, directorylist /downloads/sysopfiles
     [end]

---------------------------------------------------------------------------------

NAME
     FILEVIEWER <application>

SYNOPSIS
     FILEVIEWER /usr/bin/less

ERRORS
     NONE

DESCRIPTION
     Sets name and location of the external command to use when viewng 
     files under directorylist.

     See directorylist for examples.

---------------------------------------------------------------------------------

NAME
     DOWNLOADSCRIPT <script file>

SYNOPSIS
     DOWNLOADSCRIPT download.sfi

ERRORS
     NONE

DECRIPTION
     Sets name of script used for downloads, used under directorylist.

      See directorylist for examples

---------------------------------------------------------------------------------

NAME
     SHELL <file>

SYNOPSIS
     SHELL /usr/local/sauron/door/door.sh %node%

ERRORS
     Sets %error% true on error and logs in error.log

DESCRIPTION
     Executes a command shell for calling external programs.
     can contain system variables.

     eg:

     yesno "Would you like to read your mail? (Y/N) : "
     if %yn% = %false% then SKIPMAIL
     shell /usr/local/sauron/bin/elm.sh

     :SKIPMAIL
     execute main.sfi

     eg:

     [begin]
       m,  3, shell /usr/local/sauron/bin/elm.sh %username%
       e,  0, execute main.sfi
       g,  0, execute logoff.sfi
    [end]

---------------------------------------------------------------------------------

NAME
     DOORCOM - Executes a door shell file, creates DORINFO0.DEF

SYNOPSIS
     DOORCOM <SCRIPT FILE> - doorcom /usr/local/sauron/door/door.sh

ERRORS
     Returns 0 (OK)  1 (ERROR) in  %error%

DESCRIPTION
     Creates DORINFO0.DEF in users home directory or DORINFO0.DEF.<HOSTNAME>
     for guest users, and executes the door shell script.

     Door programs must read dorinfo0.def file to find out necessary
     information on such as the COM port, baud speed, the user's name, etc.

     Ways of telling the door prgram where to find the drop file vary from
     from program to program. In most cases you will need to write a short
     shell script to set up a door, if one is not already supplied.

     eg: Shell Script

     #!/bin/sh
     if [ " $(whoami)" = "guest" ]
      then
        DORINFO=dorinfo0.def.${REMOTEHOST}
      else
        DORINFO=dorinfo0.def
     fi

     cd /usr/local/sauron/door/smurf
     ./smurf ${HOME}/${DORINFO} $1
     cd /usr/local/sauron/bin

     Example (1) Sauron Script
     -------------------------

     print "Accessing door...."
     wait 100
     doorcom /usr/local/sauron/door/door.sh %node%
     if %error% = %false% then OK
     print "OOPS An Error.."
     wait 2000

     :OK
     execute main.sfi

     Example (2) Sauron Script
     -------------------------
     [begin]
       d,   1,  doorcom /usr/local/sauron/door/door.sh %node%
     [end]

---------------------------------------------------------------------------------

NAME
     RESETTIME                

SYNOPSIS
     RESETTIME                 

ERRORS
     NONE

DESCRIPTION
      Resets user online time to 0. Can be used with guest accounts.

---------------------------------------------------------------------------------

NAME 
     COLOURTOGGLE             

SYNOPSIS
     COLOURTOGGLE             

ERRORS
     NONE

DESCRIPTION
     Switches between ANSI colour & ascii

     There must be <scriptfilename>.asc in the MENU directory to be able
     use non-colour menus.

---------------------------------------------------------------------------------

NAME
     YESNO [text]                    

SYNOPSIS
     YESYNO "Would you like to leave feedback (Y/n) : "

ERRORS
     NONE - Sets %YN% true for yes

DESCRIPTION
     Yes and No input waits for user to enter either a Y or N.  
     Sets var %YN% true = Y false = N

     Can contain system variables.

     eg:

     promptquoteson
     yesno "Are you sure you want to logoff? (Y/N) : "
     promptquotesoff
     if %yn% = %true% execute logoff.sfi
     execute main.sfi

---------------------------------------------------------------------------------

NAME
     DISPLAYQUOTES            

SYNOPSIS
     DISPLAYQUOTES            

ERRORS
     Errors are logged in error.log

DESCRIPTION
     Displays a random line from the file /usr/local/sauron/sys/quote.txt
     in a script menu.

---------------------------------------------------------------------------------

NAME
     UPDATEUSERBULLETIN       

SYNOPSIS
     UPDATEUSERBULLETIN       

ERRORS
     NONE

DESCRIPTION
     Updates user bulletin number to lastest number.

     eg:
 
     if %userbulletin% <> %bulletinnumber% then SHOWBULLETIN
     execute main.sfi

     :SHOWBULLETIN
     printfile /usr/local/sauron/text/bulletin.txt
     pause
     updateuserbulletin
     execute main.sfi

---------------------------------------------------------------------------------

NAME
     CREATEACCOUNT            

SYNOPSIS
     CREATEACCOUNT            

ERRORS
     Errors are logged in error.log

DESCRIPTION
     Creates an account for a new user in adduser.dat ready to 
     be created with sadduser.

     Guest/Users userinfo.data is tagged with a registered flag as
     once the account is saved in the adduser database.

     Database: /usr/local/sauron/newuser/adduser.dat

     eg:

     if %registered% = %true% then EXIT
     JoinUserName "%f:red%(required) %f:yellow%Desired user name max 8 chars) : "
     if %error% = %true% then EXIT
     Print
     Print
     JoinPass "(required) Password : ","(required) Verify Password : "
     Print
     Print
     print "Remember to allow upto 1 hour for your account to be activated."
     Print
     yesno "Submit Form For Membership (Y/n) : "
     if %yn% = %false% then EXIT
     createAccount 
     :EXIT
     execute main.sfi

---------------------------------------------------------------------------------

NAME
     JOINUSERNAME <text>
 
SYNOPSIS
     JOINUSERNAME "Please enter a username "

ERRORS
     Display error if a chosen username already exists.

DESCRIPTION
     New user signup, asks for a username to use on the BBS, checks against 
     users in adduser.dat and existing linux users.

     Also checks against a list of banned names which can not be used on the 
     system. These are stored in: /usr/local/sauron/sys/banned.txt

     see createaccount for an example.

---------------------------------------------------------------------------------
NAME
     JOINPASS <text>,<text>    

SYNOPSIS
     JOINPASS "ENTER PASSWORD ","VERIFY PASSWORD"

ERRORS
     NONE

DESCRIPTION
     New user ask password to use on the BBS

     for example see createaccount

---------------------------------------------------------------------------------

NAME
     GETUSERINFO1
     GETUSERINFO2
     GETUSERINFO3
     GETUSERINFO4
     GETUSERINFO5
     GETUSERINFO6
     GETUSERINFO7
     GETUSERINFO8

DESCRIPTION
     Get addtional user information

---------------------------------------------------------------------------------
NAME
     CREATEPASSWORDTAG  

SYNOPSIS
     CREATEPASSWORDTAG

ERRORS
     Sets %error% to true on failure

DESCRIPTION
     Creates a file called password.tag in  users home directory. this file
     contains the old/new passwords needed by changepassword.sh in order
     to change the users password.


     * IMPORTANT *
     Createpasswordtag must be called prior to calling the changepasswd script.
     Do not use for guest accounts.

     See: script/password.sfi for example

---------------------------------------------------------------------------------

NAME
     SELECTMESSAGEAREA [forum no]
     CHANGETOMESSAGEAREA [forum no]

SYNOPSIS
     SELECTMESSAGEAREA        
     SELECTMESSAGEAREA  1
     CHANGETOMESSAGEAREA 2

ERRORS
     Displays error if forum no is not found

DESCRIPTION      
     If a forum number is obmitted, the command will display a complete
     list of current forums.

     eg:

     changetomessagearea 2
     execute guestforum.sfi

     eg:

     [Begin]
        l,    1,   SelectMessageArea
     [End]

---------------------------------------------------------------------------------

NAME
     ENTERMESSAGE             

SYNOPSIS
     ENTERMESSAGE             

ERRORS
     NONE

DESCRIPTION
     Post message into selected forum.

     eg:

     [begin]
       p, 1, entermessage
     [end]

---------------------------------------------------------------------------------

NAME
     READMESSAGES             

SYNOPSIS
     READMESSAGES             

ERRORS
     NONE

DESCRIPTION
     Read posts in selected forum

     eg:

     [begin]
       p, 1, readmessages
     [end]

---------------------------------------------------------------------------------

NAME
     SELECTMAINFILEAREA   

SYNOPSIS
     SELECTMAINFILEAREA

ERRORS
     NONE

DESCRIPTION
     Display lists of available file areas. Selected file area is stored in
     %mainfilearea%

     eg:

     [begin]
        s, 1, selectmainfilearea
     [end]

---------------------------------------------------------------------------------

NAME
     SELECTFILEAREA   

SYNOPSIS
     SELECTFILEAREA

ERRORS
     NONE

DESCRIPTION
     Display lists of available sub file areas. A sub file area will not be
     displayed if the user does not have access rights.
     
     Selected sub file area is stored in %filearea%

     eg:

     [begin]
        s, 1, selectfilearea
     [end]

---------------------------------------------------------------------------------

NAME
     LISTFILES   

SYNOPSIS
     LISTFILES

ERRORS
     Errors into error.log and displays no files message to user

DESCRIPTION
     Display all files which are part of the sub file area.

     eg:

     [begin]
        l, 1, listfiles
     [end]

---------------------------------------------------------------------------------

NAME
     SEARCHFORFILE

SYNOPSIS
     SEARCHFORFILE

ERRORS
     Errors in error.log

DESCRIPTION
     Searches for desired text in all sub file areas in selected main file area
     and displays results. Files can be tagged for download.

     eg:
      
     [begin]
       s,  2,  searchforfile
     [end]

---------------------------------------------------------------------------------

NAME
     MANAGETAGS

SYNOPSIS
     MANAGETAGS

ERRORS
     NONE

DESCRIPTION
     Manages files tagged for download

     eg:

     [begin]
        m, 1, managetags
     [end]

---------------------------------------------------------------------------------

NAME
     MAKETAGLIST   

SYNOPSIS
     MAKETAGLIST

ERRORS
     Errors into error.log, sets %error% to true and displays no tagged files

DESCRIPTION
     Creates a taglist (files.tag or files.tag.<hostname> for guest users) in the 
     users home directory of the files to be downloaded.

     This file is used by the downloadtags.sh script.

     eg:

     print "%f:red%Preparing files for download..... %f:yellow%"
     print
     maketaglist
     if %error% = %false% then TAGOK
     execute file.sfi
     :TAGOK
     shell %bindir%downloadtags.sh

---------------------------------------------------------------------------------

NAME
     DELETETAGLIST   

SYNOPSIS
     DELETETAGLIST

ERRORS
     Errors into error.log

DESCRIPTION
     Deletes users taglist (files.tag or files.tag.<hostname> for guest users)

     eg:
   
     print "Download complete.."
     ; Update file statistics
     updatefiledownload
     ; Remove the users file tags
     deletetagfile
     execute files.sfi

---------------------------------------------------------------------------------
NAME
     UPDATEFILEDOWNLOAD                   

SYNOPSIS
     UPDATEFILEDOWNLOAD

ERRORS
     Errors in error.log

DESCRIPTION
     Updates file download statistics in file database

     eg:
      
     example see deletetags

---------------------------------------------------------------------------------
NAME
     GETULFILE

SYNOPSIS
     GETULFILE

ERRORS
     Sets %error% to true

DESCRIPTION
     Single file upload.

     User must enter the full filename and upto a 18 line description. An error 
     event will occur if no filename is entered.

     creates (upload.tag or upload.tag.<hostname> for guests) in users home
     directory, which is used by upload.sh

     If the uploaded filename does not match the filename entered, upload.sh will
     exit with an error and the file will be removed. see upload.sh

     upload.sh will move the file from the temporary upload directory to the 
     correct file repo. see upload.sh

     eg:
      
     GetUlFile
     if %error% = %false% then TAGOK
     execute file.sfi
     :TAGOK
     shell %bindir%upload.sh

---------------------------------------------------------------------------------

NAME
     UPDATEUPLOAD

SYNOPSIS
     UPDATEUPLOAD

ERRORS
     Sets %error% to true, errors into error.log

DESCRIPTION
     Adds uploaded file data, description to file database.

     Reads in the file data from upload.tag (or upload.tag.<hostname> for guests) 
     in the user home directory created by upload.sh. If this file cannot be read
     then an error will occur and the file will not added the file database. The
     file will however, still be in the file repo.

     By default all uploaded files need to be released by a level 9 user (sysop)
     before users can download. This does not apply to level 9 users.

     eg:
      
     print "Upload complete.."
     updateupload
     execute file.sfi

---------------------------------------------------------------------------------

NAME
     OPENFILE <file>          

SYNOPSIS
     OPENFILE /usr/local/sauron/temp/%username%.bug

ERRORS
     Log errors into error.log

DESCRIPTION
     Opens Text File Appending.

     Note: Once the file is finished, it must be closed with
     closefile

     eg:
     
     OpenFile /usr/local/sauron/temp/report.bug
     Print "SAURON PROBLEM REPORT.."
     Print
     Prints "PC TYPE : 386DX/486SX/486DX/PENT > "
     inputofile
     closefile

     yesno "Submit Form (Y/n) : "
     if %yn% = %false% then EXIT

     ;Mail Form To Sysop
     shell mail -s Bug_Report root < /usr/local/sauron/temp/report.bug
     shell rm /usr/local/sauron/temp/report.bug

     :EXIT
     execute main.sfi

---------------------------------------------------------------------------------

NAME
     CLOSEFILE   
             
SYNOPSIS
     CLOSEFILE

DESCRIPTION
     Closes Currently Opened File

      for example see openfile

---------------------------------------------------------------------------------

NAME
     INPUTTOFILE     
         
SYNOPSIS
     INPUTTOFILE

DESCRIPTION
     Writes text to open file

     for example see openfile

---------------------------------------------------------------------------------
MENU SCRIPT 

     [BEGIN]                  

     Start command mode of script file interpreter

     [END]                    

     End of command mode

     STOP                     

     Use this command at the end of all script files acts as a saftey net stops script file
     going into endless loop

    Example 1
    ---------
    [Begin]

     e,    0,   Execute main.sfi
     l,    1,   SelectMessageArea
     a,    1,   EnterMessage
     r,    1,   ReadMessages
     ?,    0,   Menu
     g,    0,   Execute logoff.sfi
   [End]
   stop

---------------------------------------------------------------------------------


SYSOP COMMANDS
==============

---------------------------------------------------------------------------------

ADDMESSAGEAREA           

Sysop Command: Add new message area

REMOVEMESSAGEAREA        

Command disabled

CHANGEBULLETINNUMBER         

Sysop Command: Change Bulletin Number

