NAME
qcontrol -- dedicated *nix-quake wrapper
qcentre -- qcontrol XWindows frontend (xforms-based)


DESCRIPTION
qcontrol launches *nix-quake and accepts telnet connections
to the password protected quake console for remote server administration.


INSTALLATION

• 0. Make sure you backup your customized files from previous versions.
  
• 1. edit the Makefile to reflect where your quake executables reside
• 2. edit qcontrol.h to set your password and one line server description

IMPORTANT: SET YOUR CONSOLE PASSWORD IN THE FILE "qcontrol.h". This can be overriden by an entry in "qcontrol.ini". Set it in qcontrol.h anyway.

• 3. type "make" to compile the sources
• 4. typing "make install" will copy qcontrol, qcontrol.ini, quaked and qcontrol.cfg to your quake directory.
• 5. edit the file quaked, qcontrol.ini and qcontrol.cfg to suit your needs/preferences. You may wrap the command using "nice" for better scheduling priority.
• 6. you may put quaked in your /etc/rc.d/rc.local or simply run quaked

NOTE: intel-linux-quake0.91 (beta release?) needs to be
run by root the first time. It creates the file
"/tmp./id1/config.cfg". Yes, that's "/tmp." with a
period. When this file is created, you can start quake
without root priveleges. You can put this lines in
your rc.local:

# start dedicated quake server
if [ -x /usr/local/games/quake/quaked ]; then
  su -c /usr/local/games/quake/quaked loginname
fi

• 7. try connecting: "telnet quake.server.net 26000" or whatever port you are using.
  

COMMANDLINE OPTIONS

-ini <inifile>
All values that are "/set"-able can be put here. Also, instead of using command line parameters, put them here one parameter per line: <variable> <value>. Take note that you cannot speficy "exename" in the inifile for security reasons, use the commandline parameter instead. qcontrol will try to save the current values to the inifile every time a qcontrol variable is modified if "autosave" is set to 1. Command-line parameters override values from the inifile. You may put comments at the inifile by putting "#" at the beginning of the line. Default: "qcontrol.ini".

-autoexec <configfile>
*will automatically send the commands from the file "configfile" to the server after startup. This may be omitted if you have configured quake to start with a map and your server variables (i.e. with autoexec.cfg). If not specified, qcontrol will (try to)
read and send to the quake server the file "qcontrol.cfg". You may need to delete/edit this file if you have configured your non-qtest server to use the "autoexec.cfg" loading feature. You may put comments at the configfile by putting "#" at the beginning of the line.

-maxplayers <N>
*will launch quake with the commandline "-dedicated N". If not specified in the commandline, the default number 8 will be used.

-game <gamename>
*will launch quake with the commandline "-game <gamename>". If not specified in the commandline, the default game "id1" will be used.

-udpport <portnumber>
*tells which port xquake will accept connections. Useful if you have several games running on a single machine. Default: 26000.

-port <portnumber>
*tells which port qcontrol will accept connections. I suggest that you use the same port that your quake server is using. This will make it easier for server status seekers to find and connect to qcontrol. You don't have to worry about port conflicts because quake uses UDP while qcontrol uses TCP for console connections. Defaults to 26000.

-logfile <filename>
*specifies the filename for logging. If no filename is used, the default "qcontrol-%d.log" will be used, where %d is the port nuber used by qcontrol.

-loglevel <N>
*sets the behaviour of the logging facility, where N is:

0: nolog
1: log connection and authentication messages
2: log commands
3: 1 and 2
4: log console output
5: 1 and 4
6: 2 and 4
7: all (default)

You can dynamically set the level of logging using the "/set loglevel" command. However, if the console-server is started with loglevel 0, the logfile will not be opened and setting the loglevel to a higher level from the console server will have no effect. The default loglevel is 7.

-exename <filename>
specifies the executable filename of the quake server. Do not include the absolute path -- you must set the path in the Makefile. Defaults to "xquake".

-connectime <seconds>
*specifies maximum qcontrol connection time in seconds. Default: 600.

-passwordtries <N>
*sets the maximum number of invalid password tries before disconnecting client. Default: 3.

-autosave <0|1>
*if set to 1, qcontrol will automatically try to save the configuration to the inifile every time a qcontrol variable is changed. Default: 1.


CONSOLE+STATUS-SERVER COMMANDS

All qcontrol commands start with a "/" to avoid conflict with the quake console commands.

"214- /stat - print server status",
"214- /vars - print server variables",
"214- /banner - print qcontrol banner message",
"214- /god <password> - admin mode (console)",
"214- /crypt <password> - admin mode (console), crypted passwd",
"214- /set <varname> <value> - **set qcontrol variable value",
"214- /set - **view qcontrol variable values",
"214- /save - **save qcontrol variables to ini file",
"214- /restart - **restart server",
"214- /shutdown - **shutdown server",
"214- /help - this help message",
"214- /exit - quit",


**these commands are valid in admin mode only

/stat
will report the console's answer to a "status" command.

/vars
will list server specific variables. The console's answers to the /stat and /vars command are not recorded in the logfile to avoid bloated logs.

/banner
will display a single-line banner message.

/god <password>
Entering the admin mode with /god and the correct password will give you access to the quake server console.

/crypt <crypted-password>
same as /god except for the encryption scheme. This implements a simple password protection scheme using UNIX crypt. The server will send a random 2 letter salt at the qcontrol login (enclosed in parenthesis). Use the function "crypt(password, salt)" to get the crypted password. Remove the salt from the crypted password (first two chars) and use the "/crypt <crypted-password>" command.

IMPORTANT: SET YOUR CONSOLE PASSWORD IN THE FILE qcontrol.h
The password entry in the inifile will override this default.

/restart
will restart your quake server (and disconnect you from the console).

/shutdown
will shutdown qcontrol, quaked and your quake server (and disconnect you from the console).

/set <varname> <value>
can be used only for setting qcontrol specific variables. It cannot affect your quake server settings except for the game, maxplayers and udpport (will take effect in the next /restart). You must enter admin mode with /god and use the quake console to set quake-specific variables.
Typing "/set" only without the variable name and value will list all the qcontrol specific variables. The current qcontrol specific variables with their default values are:

# These variables will not take effect until next restart
# Modified game name (same as -game <gamename>)
game "id1"

# Maximum number of players (same as -maxplayers <N>)
maxplayers 8

# UDP port where quake listens (same as -udpport <portnumber>
udpport 26000

# TCP port qcontrol listens to (same as -port <portnumber>
port 26000

# quake server config file (same as -autoexec <filename>)
autoexec "qcontrol.cfg"

# These variables takes effect immediately after /set-ing
# Loglevel (same as -loglevel <N>)
loglevel 7

# Maximum console connection time (same as -connecttime <secs>)
connecttime 600

# Console password (no corresponding command-line arg)
# <defaults to the value you put in qcontrol.h>
password "put your password here"

# Maximum password entry retries (same as -passwordtries <N>)
passwordtries 3

# Single-line banner message (no corresponding command-line arg)
# <defaults to the value you put in qcontrol.h>
banner "Quake Control Center"

# <0|1> Auto-save config to inifile (same as -autosave <0|1>)
autosave 1

FAQ (with answers)
Q. Why do I get the message "Sock_Open: bind: Address already in use"?
A. Maybe there is another program, qcontrol or xquake using the same port.
If you can't find the conflicting program, wait for a minute and retry.

Q. Where can I get linux-quake?
A.

• ftp.cdrom.com/pub/idgames/idstuff/unsup/intel_linux_quake101.tgz (v1.01)
  
• ftp.cs.helsinki.fi/pub/People/Torvalds_Linus/testing/ (v1.06?)
  

Q. I only have the shareware version of quake, can I still use qcontrol?
A. Yes, comment out the line "REG=-DREGISTERED" in the Makefile.
Register now.

Q. Can you cheat in multi-player quake?
A. No.

Q. Why not use /satan instead of /god?
A. It's harder to type.

Q. Is there a God?
A. Yes.

Q. How do I log IP addresses each time a player enters my server?
A.

1. Edit the Makefile and uncomment the lines enabling logging of IP addresses
2. Edit qtcp-v1.01/Makefile
3. Follow normal compilation/installation instructions
4. Patch your Quake version 1.06 progs.dat to print player names at connection -- using the client.qc (in the "qc" directory) as sample.

CHANGES

v0.04
- fixed hangup bug related with connecttime timeout
- removed "logfile" in /set-able vars (security -- to avoid overwriting files, use "-logfile" in cmdline instead)
- changed connecttime default to 3600 seconds (one hour, for qcentre connections)
- ported to Solaris 2.4 and SunOS 4.1.3 (in anticipation for Quake ports to these platforms)
- distributed with an XWindows/xforms frontend program: qcentre v0.04a (Linux ELF binary only, dynamically linked)
- added option for logging IP address of game connections (must install a QuakeC patch to work)

v0.03
- detects and restarts after xquake crashes
- added simple challenge-based password encryption using UNIX crypt
- added support for patch loading: -game <gamename>
- added support for using another udpport for quake: -udpport <port>
- added /shutdown command for stopping your server
- added /restart command for restarting your server w/ new config
- added inifile for setting config from a file
- kills running quake server when exiting/aborting qcontrol
- included XWindows frontend program: qcentre
- added console connection timeout: connecttime
- added maximum number of password tries: connecttime
- fixed permissions of logfile (logs may contain password)
- cleaned up code, added -Wall for more warnings from gcc
- new variables, new commands

v0.02
- squashed the newline logfile bug
- added step in the README on how to connect to the server :)

v0.01
- initial release


AUTHOR
A.Oliver De Guzman <oliber@aiko.upd.edu.ph>