
-----------------------------------------
README.TXT for QuakeRemote Server/Client
V1.0 (NT base release)
Beau Butler (bbutler@ihug.co.nz)
-----------------------------------------

Contents
--------
  1) Introduction
  2) Changes for V1.0
  3) Requirements
  4) Installation
  5) Usage
  6) New Stuff/Notes
  7) Known Issues
  8) Future Releases
  9) Contact Info
  10) Disclaimer
  11) (tm)


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

QuakeRemote Server is designed to allow remote administration of one or more
dedicated game servers over a TCP/IP (LAN or Internet) connection.
QR Server has the ability to start and kill server processes remotely. 

QR Currently has 100% support for the following servers:
 * Quake (dedicated)
 * QuakeWorld server
 * Quake II (dedicated)
 * Starsiege Tribes (dedicated)
 * Any other server apps that use a "dos box" style console interface
Half-life, sin and unreal dedicated support will be available soon.


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.

I will be happy to provide (limited) "technical support" if you have problems.


Changes for V1.0
----------------
[note: see Changelog.txt for changes to previous versions]

Server changes:
 - Core game server communications code has been completely re-written. It is
   now fully compatible with all console based applications.
 - Winsock comms code & QR main loop have been completely re-written to
   minimise CPU usage.
 - QR server is now an NT service, and can run fine when no-one is logged in,
   workstation is locked, etc etc.
 - The registry storage format for game server settings has changed, see
   "Defs" later in this document for details.
 - QR currently does _not_ log game server output. This is related to the new
   game server comms system, see "Known issues" below for details.
 - Game servers are run in their own seperate desktop, so as not to interfere
   with the interactive user. A utility will be provided for directly
   accessing this desktop, should the need to directly interact with the game
   servers arise.
 - QUIT command changed to SHUTDOWN. (Too many people were inadvertantly
   quitting the QR server, thinking QUIT was a logout command)
 - LOGOUT command added.
 - START command is no longer supported. Use the GUI start box.

Client
 - The window menu has a "clean up" item, for removing all the "dead" windows
   that clutter up the client after a while.
 - Server and client now encrypt sensitive data (ie logins and anything
   containing passwords) for transmission over the wire, and for storage in
   the registry. The encryption is pretty basic, but it should keep the
   packet sniffer weenies out :)


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

 - PC running Windows NT4 (server or workstation) for QR Server
   QR Server was designed for and tested mainly under NT4.0, so has no
   problems running on that platform. Unfortunately, due to the new server
   code, QR1.0 is NT only. I have not been able to test QR Server on NT3.xx 
   - try it & get back to me...
   Also, QR Server requires Winsock 2.0 or higher. This comes built in on NT4,
   so is not a problem there.
 
 - PC running 95/98/NT for QR Client
   The client runs fine under 95/98/NT. 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
------------

Still no fancy setup program - QR doesn't really need one.
How to install QR in x Easy Steps:
 
 1) Make a new empty directory somewhere. 
    Extract (unzip) QR.EXE, QR.REG and CONSOLE.DLL to it.

 2) 'run' (double-click) the QR.REG file to merge it into the registry. This
    file sets up the registry structure and default entries for options, 
    Defs etc etc.

 3) Make a directory (folder) inside the directory containing QR.EXE.
    Call it "log" - QR puts all its logfiles here.

 4) Make a directory (folder) inside the directory containing QR.EXE.
    Call it "DLL". Put CONSOLE.DLL into this DLL directory.

 5) Edit the registry to set up game server definitions (the 'Defs'
    key). See the "Defs" section below for more information.

 6) Run QR.EXE with the /I command line. This installs the QR service
    into the services control panel. The default options are Auto
    start, system account, and no interacting with desktop. Use the
    Services control panel to start and configure the QR service.

 7) Run QRCL.EXE, connect and log in to the QR server. The default
    account name is "admin", default password is "admin". Use the 
    CHPWD command to change this.

 8) Done! Fire up a dedicated server or two and experiment! 


                                    USAGE
                                    =====

The Server
----------

The QR Server is easy to use - once installed as a service, you can forget it's even there.
All of the interface functions are accessed via the client.


The Client
----------



The Servers window
------------------

This window is always present in the client - it can be minimised, but not
closed. It contains a 2-level hierarchical tree view which is used to show
QR and Quake servers. The first level is a list of all QR servers that the
client is currently connected to. The second level (ie as subtrees of the QR
server items from the first level) consists of the game servers (if any) that
that particular QR server is controlling.

Menu operations (e.g. "disconnect") are performed on the server that is
currently selected in the servers window. Double clicking a server will pop
up its console window, which can be handy if there are a large number of
windows in use.

The Start Window
----------------

This window consists of 4 parts:
 - a Host selection box - selects the machine to start the game server on,
 - a Type selection box - selects the type of game server to start,
 - a Command Line edit box - enter command line options for the game server.
   "-dedicated" and it's equivalents do not have to be specified. This parameter
   is specified for each server type by the 'DediCmd' registry entry. (See "Defs")   
 - a Window Title box (this is optional and simply specifies the name to
   appear in the title bar of the server's console window in the client.)

The start button starts the server, the cancel button quits without starting. Note that the contents of the commandline and window title boxes are not cleared in between starts.

The Menus (and toolbar)
-----------------------

Most of these menu items have equivalent toolbar buttons.

 System menu

Connect - This brings up the Connect dialog box, where you can connect to a
          QR server (see Connecting)
Start   - This brings up the Start Server window, where you can set settings
          and start a new game server. (see The Start Window)
Show Servers - Brings the Servers window to the front (also restores it if
               minimised)
Exit    - Closes all connections and quits the client

 Server menu

Disconnect: Disconnects from the server currently selected in the Servers
            window. This action only applies to QR servers - if a game server
            is currently selected, this menu item is disabled.
Window:     Brings up a window for the selected server if one does not exist
            already. If a window already exists, it will be restored to its
            normal size and brought to the front. Note that this is the same
            as double-clicking on a server in the Servers list.

 Window menu

This menu contains the standard windows window manipulation functions.
(cascade, tile etc)
It also contains the "clean up" item, which closes all "dead" windows.

 Help menu

As there is no fancy online help (this is it :-), this just has an about box,
which will display the version number of the client and whatever else.


The Server windows
------------------

These windows are the same for QR and game servers. 
This is currently just one tab, the server's console.
Operation is the same as usual, type something in the edit box at the bottom,
hit enter, and whatever you get back will be shown in the output box...


                             Operations (Doing Stuff)
                             ========================

Connecting
----------

Just specify the IP address of the QR server machine (_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 admin/admin). The Server disconnects after 3 unsuccess-
ful logins.

Commands
--------

Once logged in, the "QR Server" console window for that QR server should pop
up. This is where you give commands to QR and where it displays status
messages. QR supports only a limited number of commands via this console,
as most of it's functionality is supplied via the GUI parts of the client.


These are the current (V1.0) commands available (Commands are case insensitive)
Some commands that were present in previous versions are currently not supported. 

HELP
 Lists available commands.

SHUTDOWN 
 Shuts down the QR server. The same can be accomplished using the Services
 control panel, or any service control program. Note that QR leaves any
 game servers running when it shuts down.


EXEPATH/EXENAME
 These two commands are no longer available. Exename/path has been replaced
 by the server definition registry entries. (See "Defs"). This means using
 regedit on the server machine for now.

PORT portnumber
 ..Is currently not available either. Use Regedit :)

RUN filename
 ..Ditto. Did anyone actually use this?

START servertype "name" command_line_parameters
 ..Is obsolete. Use the Start button 


KILL id
 ..Has been temporarily disabled.


NEWUSER
 Pops up the New User dialog box, which then creates a new user.
 Note that only 'admin' can do this.

CHPWD
 Pops up the Change Password dialog box.
 Note that only 'admin' can change other peoples passwords.



New Stuff
---------

 Defs
 ----

The old Exename/Exepath system has been replaced with a new set of registry
keys, stored under HKEY_LOCAL_MACHINE\SOFTWARE\QR\QR_1.0\Defs
Under the Defs key are several keys ("folders"), each one representing a
different server type.
The sub-key name is the name of the server type which will appear in the
client's Start Server dialog.
for example: HKEY_LOCAL_MACHINE\SOFTWARE\QR\QR_1.0\Defs\QuakeWorld contains
values relating to QuakeWorld servers, and the word "QuakeWorld" will appear
in the Start Server dialog box's drop down list.
Example entries are included for Quake, Quake2, QuakeWorld, and Tribes.
Each sub key has a number of value items, their names and purposes are as
follows:

 "Use" (REG_DWORD/integer value) : This value must always be present for
       a Def entry to be read. If set to 1, this def entry (server type)
       is enabled, and will show up in the client's start server dialog.
       If set to 0, this entry is disabled, and will be ignored.

 "EXEPath" (REG_SZ/string value) : This is a string specifying the path
       and filename of the executable file to run when this server type
       is selected. This replaces the old EXEPATH/EXENAME commands, as well
       as the Run branch of the registry.

 "DediCmd" (REG_SZ/string value) : This string specifies the commandline
       parameter used to put the launched server into dedicated mode.
       e.g. for quake "-dedicated" etc. Note - some servers do not require
       this parameter (e.g. qwsv), in this case it is set to an empty string.

 "DLL" (REG_SZ/string value) : This string specifies the name of the QR DLL
       to use to communicate with the launched server. Currently only
       console.dll is supported - console.dll is used for all quake servers,
       Tribes, and any other "Dos box" like console process. This string is
       only a filename, no path, as all QR DLLs are stored in the DLL
       subdirectory under the QR directory.

 "Interval" (REG_DWORD/integer value): This integer specifies the interval
       in milliseconds between checks on the controlled server's console
       output. (See "Server control" in "Known Issues" for more info)

 "DisplayType" (REG_DWORD/integer value): This integer specifies the method
       that the client must use to display returned info from a particular
       server type. Currently this value must be set to 2 for all server
       types.


 Users
 -----

QR features multiple user 'accounts'. Currently these serve no purpose
other than to identify who logged on when and did what, for the log files.
Security rights for various types of user have not yet been implemented.
QR comes with one built-in account, "admin". If the registry key for the
admin user is deleted, it will be recreated with the default password,
also "admin". The NEWUSER and CHPWD commands can be used to manage user
account names.
The admin user can do three things that other users can't - create new
users, change the passwords of other users, and issue the SHUTDOWN command.
Other than that, there is no difference between admin and any other user.



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

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

1) Beta/Shareware/Freeware/copying etc
   QR is completely freeware. The 3 server "cripple" has been removed.
   QR is NOT to be sold or modified in any way without my express permission.
   For those wishing to develop custom clients, the protocol spec (such that
   it is) :) is available on request.

2) Registry protection
   The Users key of the registry is not currently protected by any advanced
   NT security features. It is possible for someone who has sufficient
   interactive (or remote registry) access to the qr server machine to view
   and modify these values. These values are encrypted, however, making it
   difficult for someone to determine login passwords. If the admin user's
   password is deleted, QR will reinstate the admin value next time it  
   restarts.
   
3) Server control
   QR cannot currently 'attach' to a running game server and communicate.
   This is theoretically possible, but as not been implemented yet.
   This has certain implications:
   1) Servers started by something other than QR will be invisible to QR.
   2) Servers left running if QR shuts down will be 'orphaned', as QR
      currently cannot re-attach on startup. As these server consoles reside
      on their own desktop, the administrator would have to log in to the
      server machine and use a desktop utility (QRDS.EXE) to gain access to
      this desktop in order to control the game servers manually.
   The control code no longer has any annoying side-effects, like previous
   versions did. (no blank windows, foreground switching, etc)
   Also, there are no longer any problems with quakeworld servers.


4) There is no longer any vbsk, qrsk, or anything even remotely like it.
   (phew)



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 USE OF THIS SOFTWARE. THIS IS FREEWARE,
 USE IT AT YOUR OWN RISK.

Trademarks
----------

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

