
The following are the step by step procedures used to install QuakeBBS on
your system and get it up and running to accept users.

Assumptions:
~~~~~~~~~~~

In the following steps, we assume you have already obtained a copy of the
QuakeBBS installation archive and have untarred the files into a unique
directory.  For purposes of these examples, we'll assume you have put the
files in /usr/quakebbs (although they really could be anywhere you like).


1)  First let's check your QuakeBBS directory.  You should have the
    following files and directories at this point:

      quakebbs/                        <- QuakeBBS home directory
          |
          +-- data/                    <- QuakeBBS data files directory
          |     |
          |     +-- quake.in           <- Sample Quake Server input FIFO
          |     +-- quakebbs.users     <- QuakeBBS User Database
          |
          +-- file/                    <- File Base support directory
          +-- logs/                    <- QuakeBBS log files directory
          |     |
          |     +-- quake.log          <- Quake Server output file (+)
          |     +-- quakebbs.log       <- QuakeBBS log file (+)
          |
          +-- mesg/                    <- Message Board support directory
          +-- server_utils/            <- directory for Quake Server utils
          |     |
          |     +-- README.server      <- Text file explaining the utils
          |     +-- qconsole*          <- QConsole utility
          |     +-- startserver*       <- Script to help start Quake Server
          |
          +-- text/                    <- User modifiable text file dir.
          |     |
          |     +-- README.text        <- File describing text files
          |     +-- noconnect.udp      <- Displayed to errant Quake Client
          |     +-- prelogin.mesg      <- Displayed before login
          |     +-- quakebbs.help      <- Displayed for '/help' command
          |     +-- welcome.mesg       <- Displayed after login
          |
          +-- qbbsuser*                <- QuakeBBS User utility
          +-- quake.servers            <- Quake Server configuration file
          +-- quakebbs*                <- QuakeBBS main executable
          +-- quakebbs.conf            <- QuakeBBS configuration file

    If you are missing any of the directories above, please check to be
    sure you untarred the QuakeBBS archive correctly.  The 'file' and
    'mesg' directories are not yet used (as of this writing).  Those files
    marked with a (+) after the description will be created the first time
    you run QuakeBBS.

2)  Copy the executable files in the server_utils directory (qconsole and
    startserver) into the directory you have xquake installed.

3)  Modify the following files to suit your system:

        quakebbs.conf       This file holds all the QuakeBBS user
                            configurable information.  Be sure to change
                            the *_DIR settings if you installed QuakeBBS
                            somewhere other than /usr/quakebbs.  This file
                            is heavily commented, however, additional
                            information can be found in the quakebbs.README
                            document.

        quake.servers       (Or the value of QUAKE_SERVER_FILE in your
                            quakebbs.conf file).  Describes the Quake
                            Servers configured on your system.  Make note
                            of the ShortName field, as this will be needed
                            in one of the later steps.

        startserver         (In your xquake directory).  There are a few
                            lines near the top of this script file you will
                            need to change to match your system (especially
                            if you changed any of the default values in
                            quakebbs.conf).

4)  Run the qbbsuser utility from your QBBS_HOME_DIR (it must be run from
    this directory).  Follow the instructions in quakebbs.README to add
    yourself as a user and modify the "new" and (optionally) "guest"
    accounts.

5)  If you changed the ShortName field in your quake.servers entry, you
    will need to create a special FIFO file in your QBBS_DATA_DIR
    directory.  A sample FIFO (quake.in) is included in the archive, and
    if you left the default 'quake' ShortName in the quake.servers file,
    you can skip this step, as QuakeBBS will happily use it.

    To create a FIFO file, first cd into your QBBS_DATA_DIR directory.
    Then run the 'mkfifo' command (run 'man mkfifo' for help) as follows:

        mkfifo <shortname>.in

    (change <shortname> to whatever you used in your quake.servers file).
    
    If you don't have the mkfifo command or get some other error, you will
    have to use the FIFO provided in the archive and must keep your server
    ShortName set to "quake"

6)  cd to the main QuakeBBS home directory and run 'quakebbs'.  It will
    display the QuakeBBS copyright screen and provide information as to
    which files it is reading its configuration from and begin running in
    the background.  If you examine the output of your quakebbs.log file
    and/or your syslog file, you should see messages confirming that
    QuakeBBS is waiting for connections.  If your Quake server is not yet
    running (see step 6), you will see messages reguarding 'mesgrecv'
    errors.  This is normal and should stop once the server is started.

7)  If your Quake server is already running, first shut it down using
    normal means.  
    
    cd to your xquake directory and run the startserver script.  If all
    goes well, you should get a "Quake Command >> " prompt.  Tapping ENTER
    a few times should print the normal xquake startup messages to your
    screen.  Now try entering 'status' at the prompt and hit return.  You
    should get the normal Quake response back in a few seconds.

As long as you didn't get any error messages except those previously
described as normal, during the above steps, QuakeBBS should be up and
running on your system.  You can test this by telnetting to your system at
the port you have specified for TCP in your quakebbs.conf file.  You should
get a 'Username' prompt and be able to log in.  Try running the /who and
/quake commands.  /who should display the users on your system (probably
only you at this point), and /quake should tell you it is sending a request
for authorization and return an accept or reject reply within
QBBS_CONTROL_WAIT seconds.

If you have any trouble not covered above, please read the quakebbs.README
file.  If your questions aren't answered there, please send mail to
donovan@mindspring.com and I will help as best I can.  Thanks!

Donovan C. Young
donovan@mindspring.com
http://www.mindspring.com/~donovan/quakebbs

