
-----------------------------------------
README.TXT for QuakeRemote Server/Client
V0.90 (BETA)
Beau Butler (bbutler@ihug.co.nz)
-----------------------------------------


Contents
--------
  1) Introduction
  2) Requirements
  2) Installation
  3) Usage
  4) Known Issues
  5) Future Releases
  6) Contact Info
  7) Disclaimer
  8) (tm)

Introduction
------------

QuakeRemote Server is designed to allow remote administration of one
or more Quake dedicated servers running on a Windows NT machine over
a TCP/IP (LAN or Internet) connection. QR is fully compatible with Vanilla
Quake (WINQUAKE.EXE) and Quake II running in dedicated server mode, and
(currently) partially compatible with QWSV.EXE (see part 4). QR Server has
the ability to start and kill quake server processes remotely. QR also fully
logs all server output and any entered commands.

QR Client/Server is not intended as a replacement for rcon - it has been
developed mainly for vanilla quake. However, it is fully compatible (or
should be :), and has a few advantages over rcon:
 - Multiple user/password security
 - QR can be used to _start_ quake servers remotely,
 - Multiple servers can be controlled from the one (MDI) client (see 3),
 - Everything gets logged,
 - No need to start quake just to control the remote server.

Any feedback regarding this program would be appreciated - comments,
flames, rants, bug reports (hopefully not too many of these :), ideas
or pretty much anything else, email:
 bbutler@ihug.co.nz
or ICQ me on 1062482.

There is also a webpage at: 
http://homepages.ihug.co.nz/~bbutler/qr
where the latest programs/docs etc will be.
Remember that this program is beta software, Use At Your Own Risk. 
Having said that though, I will be happy to provide (limited) "technical
support" if you have problems.


Requirements
------------

 - PC running Windows NT 4.0 for QR Server
 QR Server will run on windows 95, but you will not be able to send commands
 to the Quake server processes. This is the only problem that win95 has with
 QR - everything else is (should be) fine. This is due to the different ways
 in which 95 and NT4 deal with console processes. As QR fully supports 
 command line parameter passing and can kill the server processes itself 
 if needed, this may be all you need.
 I have not been able to test QR Server on NT3.xx - try it & get back to me. 
 
 - PC running 95/NT for QR Client
 The client runs perfectly in 95. Note that as QR is a win32 application,
 it will not run under a 16 bit windows. A 16-bit client shouldn't be a
 problem - if anyone needs one, mail me.


Installation
------------

No fancy setup program as yet - this is beta, after all.
How to install QR in Ten Easy Steps:

 1) Unzip the server package to anywhere you want.
 2) Ensure that HAR.EXE and VBSK.EXE are in the same directory as QR.EXE
    - important, QR only looks for those programs there.
 3) Copy VB40032.DLL to your system Directory 
    - VBSK needs this (see part 4 for information on VBSK).
 4) Double click on (or run) the QR.REG file to set up the registry
    structure and default entries.
 5) Make a directory (folder) inside the directory containing QR.EXE.
    Call it "log" - QR puts all its logfiles here.
 6) Unzip the Client package somewhere (on the same machine is OK for
    this setup procedure, but not recommended for normal usage - see part 4)
 7) Fire up the client and connect to the QR server. (127.0.0.1 for loopback
    if its running on the same machine). The default port is 4044 - this can
    be changed.
 8) If the connection succeeds, you should get the login box. 
    Login: "1" Password: "1" (without the quotes) - this is the default
    'account' set up by QR.REG - get rid of it ASAP :), see parts 3 & 4 for
    info on users.
 9) Use the EXEPATH and EXENAME commands to tell QR the names of your
    quake/quake2/qwsv executables and their directories. (see part 3
     - commands)
10) Done! Fire up a dedicated server or two and experiment! 


Usage
-----

The Server

 The QR Server is easy to use - all you do is run it! All of the interface
 functions are taken care of through the client. At this stage QR Server has
 a 'status' window which it prints messages to - most of which appear in the
 main console window of the client (if you are connected) - and which also
 get logged to CONxxx.LOG (whether you're connected or not).

The Client

 The client is very 'bare bones' at this stage. The Help menu just has an
 about box and the Window menu has the standard MDI window control functions.
 The server menu has four commands:
  Connect    : Pops up the connect dialog
  Disconnect : Closes TCP link to QR server
  Refresh    : This just ensures that what the client displays (console
               windows etc) is in sync with what the Server is doing with its
               Quake servers. Use this if you close a console window by
               accident and you want it back, for example.
  Quit       : ...Gee, a real toughie :-)

Connecting

 Just specify the IP address (NOT the computer name - DNS resolution is not
 supported at this time), port number (default is 4044), and timeout (in
 seconds) and hit connect.

Logging In

 A successful connection will pop up the login box. Specify username and
 password (default is 1/1). The Server disconnects after 3 unsuccessful
 logins.

Commands

Once logged in, the "QR Console" console window should pop up. This is where
you give commands to QR and where it displays status messages. QR is
completely Command line based - I'm not big on Bell & Whistle GUI interfaces
:-)
These are the current (V0.90) commands available - just the bare essentials
needed for proper operation.
(Commands are case insensitive)

HELP
 Displays version number and lists available commands.

SHUTDOWN
 Closes the connection, quits QR Server process, kills VBSK and any
 controlled dedicated servers (see part 4).

SYSRESET
 Same as SHUTDOWN, but waits 8 seconds then restarts QR Server. Useful if
 something goes Horribly Wrong. ;-) 

EXEPATH servertype path
 Sets/Retrieves the path to the specified servertype. (see server types
 below.) If no path is specified, QR displays the currently set one.
 Note: This stores to/reads from the registry so only needs to be used once.
 No checking is done for the existence of the specified path.

EXENAME servertype filename
 Sets/Retrieves the filename of the specified servertype's EXE. (see server
 types below.) If no filename is specified, QR displays the currently set one.
 Note: This stores to/reads from the registry so only needs to be used once.
 No checking is done for the existence of the specified filename.

PORT portnumber
 Sets/Retrieves the current port number for TCP connections to QR Server.
 If no portnumber is specified, QR displays the current setting.
 NOTE: If the port number is changed, subsequent PORT commands will display
 the new port number but QR WILL STILL BE LISTENING ON THE OLD ONE. QR has
 to be restarted for the change to take effect.

RUN filename
 Runs a program on the remote computer. Do _not_ use this to start
 dedicated servers, RUN gives you no control over the program that it starts.

START servertype "name" command_line_parameters
 Starts a dedicated server. (Probably the most complex command here.)
 The servertype parameter is a server type string recognised by QR (see
  below).
 The name parameter is optional and must be specified in quotes if it exists.
  This parameter has nothing to do with quake, it just specifies what appears
  in the title bar of the quake server's console window in the client. This
  is purely so it is easy to tell multiple servers apart in the client. If it
  is omitted, a default name is used.
 The command_line_parameters parameter is just a string of command line
  parameters which the quake server is started with. Note that "-dedicated"
  or "+set dedicated 1" is implicit and does not need to be specified, 
  although it still can be (for example, if "-dedicated 16" is required).
Some examples:
 start quake -game ctf
   vanilla quake, ctf server
 start vq "Bob's Team DM" +teamplay 2 
   vanilla quake, teamplay, "Bob's Team DM"  appears in client window title
 start winquake "Fred -dedicated 16 -game arena
   vquake, "Fred -dedicated 16 etc" in client window. Oops.
 start quake2
   standard quake 2 server
and so on... 

KILL id
 Kills a specified server (posts a WM_SYSCOMMAND / SC_CLOSE message to the
 servers window) based on the servers ID number. This is allocated when the
 server is started and appears in the server startup messages (and also in
 the default name if no name is specified). Note that it is more 'friendly'
 to use QUIT in the console window as you normally would if possible.

KILLALL
 Kills all controlled servers currently running. QR Server also does this
 automatically when it shuts down.

RESETVBSK
 Kills VBSK.EXE and restarts it.
 (See part 4 for info on VBSK and ResetVBSK).

NEWUSER
 Pops up the New User dialog box, which then creates a new user.

CHPWD
 Pops up the Change Password dialog box.


Server Types

These are used in the START, EXENAME and EXEPATH commands.
Type strings are case insensitive.
 
 Vanilla quake server (WINQUAKE.EXE _not_ Dos Quake)
 Type Number: 0
 Type Strings: "VQ", "QUAKE", "WINQUAKE", "VQUAKE"

 QuakeWorld Server (QWSV.EXE)
 Type Number: 1
 Type Strings: "QW", "QUAKEWORLD", "QWSV"

 Quake 2 Server
 Type Number: 2
 Type Strings: "Q2", "QUAKE2"

 --Added Late--
 Command Prompt (See part 4)
 Type Number: 3
 Type Strings: "CMD", "COMMAND"



Known Issues
------------

Most of these are reasons why this is still a beta.

1) Beta/Shareware/Freeware/copying etc
This is a beta release, and as such is not completely finished or nicely
'packaged'. Having said that, it is fully functional - the only 'cripple'
present is the restriction to 3 console processes at any one time. This is
just in case QR becomes shareware at a later date. If it remains freeware,
QR1.0 will be able to support a theoretical 9999 servers at once. Email me
if you think QR should remain free - I need to know whether it is worth it
to continue developing it.
QR is NOT to be sold or modified in any way. This release (0.90) is freeware.

2) Server Control
QR cannot 'attach' to a running quake server and communicate with it. For
various reasons, QR has to 'own' a server to be able to interface with it,
and QR has to start the server to be able to own it. This is also why QR
takes its servers with it when it shuts down.
The methods used to communicate with the servers have some side effects:
 - The string in the q server's title bar is it's QR-assigned ID number,
 - No output appears in the controlled server's window. If you are using the
   server computer and need to see what it is doing, a workaround is to
   examine the server's log file. This does not work for QuakeWorld servers
   however - see below.
 - Commands can still be given to the controlled server by typing in its
   window, however.
 - Every time a command is sent to a q server, that server is switched into
   the foreground, and keyboard focus is set to its window. This is currently
   a necessary evil, and hopefully will not be present in future versions.
   This has one advantage - if your NT gives more cycles to the active
   window's process, then sending a command to a server will give that server
   priority.
 
For these reasons (especially the last), it is not a good idea to run client
and server on the same machine. It is possible, but why bother? Just use a
normal server - until it's time to go home from work or whatever :-)
Also, the last reason (and some in VBSK - see below) is a good argument for
using the server machine exclusively for quake - Task switching can really
ruin the server computer's user's day! Imagine looking up at the monitor and
abruptly realising the last 30 odd seconds of typing have gone to a quake
server instead of Word :)

3) QuakeWorld Servers (QWSV.EXE) --IMPORTANT--
QWSV.EXE has an odd little quirk that Quake and Quake 2 (thankfully) do not.
When it outputs something, it does not display it immediately but instead
caches its output until enough of it has built up to make the 'cache' a
certain size, at that point it dumps the cache out all at once. This
behaviour is also noticeable when logging is enabled on a standard QWSV
console - if the logfile is periodically viewed while QWSV is running, it
will show up empty either until QWSV flushes its 'cache' or QWSV is quit.
This behaviour has affected QR too, thus you cannot see what your QWSV is
doing. Note that you can still send commands to it perfectly normally - THIS
WORKS. It is possible to get it to display something by sending the EDICTS
command - this will generally accumulate enough output to force QWSV to dump
its cache, and thus show some output. This sledgehammer approach will
probably lag out the players for a bit though!
Note that, since it is still possible to send it commands, rcon_password can
be set, then the server can be run thru rcon as normal.
If anyone can shed some light on a way to get QWSV to behave like normal
quake in this regard, could you please email me with the info. If nothing
can be done, I will probably build a 'rcon client' into QR so the behaviour
will be transparent (i.e. just like a standard quake QR console).

4) Security
The login/change/newuser passwords are currently NOT encrypted for a) storage
in the server machine's registry or b) transmission over the wire.
 a) would be a Bad Thing if some evildoer managed to get physical (or Remote
    Registry) access to the server computer, and knew how to use regedit.
    However, if that is possible, said evildoer could do much worse than just
    compromise QR's security, and the user account information can be deleted
    anyway, encrypted or no. (This is currently the only way to get rid of
    accounts - no KILLUSER command exists at this time. Make sure to delete
    the 1 / 1 account after setup is complete).
 b) is worse if there are people about who like sniffers, etc.
Anyway, there WILL be encryption in V1.0.

5) VBSK
VBSK is a temporary hack used to get your commands to the quake servers, as
more conventional (and safer) methods fail against the likes of Quake which,
being a game, is (by definition) just non-standard enough to be annoying.
VBSK involves the generation of keyboard events, so a system modal dialog box
popping up will basically screw it. (A good argument for using the server
computer exclusively for quake.) It is also the reason why QR is only partially
functional under win95.
Anyway, if you notice that your commands are not getting through to the quake
servers, it could possibly be because some busybody has closed VBSK, or VBSK
has crashed. (When testing QR, nothing crashed except VBSK, and that only
once. VBSK is also the only part of QR written in Visual Basic. ;) Try using
the RESETVBSK command - it may help.
V1.0 should have no VBSK - it will hopefully be fully internal.


Future Releases -  TODO
-----------------------

 - Fix all the above stuff
 - A client which can connect to multiple server machines
 - QR Client/Server for Linux/Xquake. If this is done, Linux and win32
   versions will use the same protocol etc for full compatibility. Run your
   Linux Quake servers from 95 at home!
 - More server commands. 
 - Timed/Batch startup/shutdown of servers.
 - Whatever else I (or others) can think of.


Contact Info
------------

You can get hold of me by:
www  : http://homepages.ihug.co.nz/~bbutler/
email: bbutler@ihug.co.nz
ICQ  : uin #1062482



Disclaimer of Warranty
======================
 THIS SOFTWARE IS PROVIDED "AS IS", WITH NO WARRANTY WHATSOEVER EITHER
 EXPRESSED OR IMPLIED.  THE AUTHOR OF THE SOFTWARE ACCEPTS NO
 RESPONSIBILITY FOR ANYTHING THAT MAY HAPPEN TO YOU, YOUR COMPUTER OR
 ANYTHING ELSE AS A RESULT OF THE SOFTWARE. THIS IS BETA SOFTWARE. YOU
 USE IT AT YOUR OWN RISK.

Trademarks
----------

Quake and QuakeWorld are registered trademarks of ID Software, Inc.
All other trademarks and service marks are the property of their
respective owners.
All rights reserved.

