![]() |
![]() |
The QstatList package is available as a gzipped tar file, containing the source and documentation files.
The package is available via FTP from:
Additional Requirements
Some installations may require the installing user to have root or root-equivalent privileges.
NOTE: Package dependencies and requirements must be met before using the installer, as it will check for the existence of the Perl libraries and set appropriate options based on what it finds.
gunzip qstatlist-x.x.tarWhere 'x.x' is the package version number. Next, un-tar the file by typing:
tar -xfv qstatlist-x.x.tarAgain, where 'x.x' is the package version number. This will create a subdirectory './qstatlist-x.x' and populate it with the tar file contents.
<full path to perl> install.pland follow the on-screen instructions. Please use care when using the install facility as it does create directories and files as well as set file and directory owners, groups, and permissions.
print(SFHOUT "die(\"Can't find qstat... terminated\") if (!((-f $QSTAT) && (-x _)));\n";On the line immediately after the $QSTAT declaration.
touch hold.dat; touch list.logSet the permissions to 0666 (-rw-rw-rw-), and set the user and group to that of the cron user set up in Step 2. [These files must be readable and writable by at least the cron user and the Web server's CGI user.]
touch list.dat; touch stats.logSet the permissions to 0644 (-rw-r--r--), and set the user and group to that of the cron user set up in Step 2. [These files must be readable and writable by at least the cron user.]
touch dnscacheSet the permissions to 0644 (-rw-r--r--), and set the user and group to that of the cron user set up in Step 2. [This file must be readable and writable by at least the cron user.]
grep -v "# debug" qstatlist.src > qstatlistThis removes the debugging output from the source. At this point you may wish to delete the qstatlist.src file.
grep -v "# debug" addqserver.src > addqserver.cgiThis removes the debugging output from the source.
grep -v "# debug" qstatwrap.src > qstatwrap.cgiThis removes the debugging output from the source.
The addqserver.cgi and qstatwrap.cgi scripts perform the server add and individual server query functions, respectively.
# ls -l /usr/netscape/suitespot/cgi-bin/qstatlist -rwxr-xr-x 1 root other 12551 Sep 24 14:26 addqserver.cgi -rwxr-xr-x 1 root other 15429 Sep 24 14:26 qstatwrap.cgi
This directory will contain the HTML output files generated byqstatlist. The icons/ directory contains QstatList support graphics, the maps/ contains the map thumbnails used by qstatwrap, and the stats/ directory contains the statistics output files and graphs.
# ls -l /usr/netscape/suitespot/docs/quake/servers drwxr-xr-x 5 spider spider 512 Jan 12 10:24 . drwx--x--x 2 root other 512 Aug 24 09:39 icons drwx--x--x 2 root other 4096 Mar 24 1998 maps drwxr-xr-x 2 spider spider 1536 Sep 23 17:33 stats
The qstatlist program generates the HTML output files for the server list (in conjunction with *.pl support files), while qstatlist.conf is the global QstatList configuration file. The server database is contained inlist.dat and hold.dat contains the temporary holding area for addqserver. QstatList uses two log files: list.log is the QstatList log file, and stats.log is the QstatList statistics log file. If DNS caching is enabled, dnscache will exist to hold the DNS cache. At this point, you may wish to copy the sample server database from the samples/ directory in the distribution so that you can generate a non-empty list.
# ls -l /usr/local/etc/qstatlist -rw-r--r-- 1 spider spider 0 Feb 11 14:23 dnscache -rw-rw-rw- 1 spider spider 0 Feb 11 14:20 hold.dat drwxr-xr-x 2 root other 512 Feb 10 14:52 lib -rw-r--r-- 1 spider spider 0 Feb 11 14:23 list.dat -rw-rw-rw- 1 spider spider 0 Feb 11 09:59 list.log -rwsr--r-- 1 spider spider 16739 Feb 11 11:08 qstatlist -rw-r--r-- 1 root other 10064 Feb 11 11:08 qstatlist.conf -rw-r--r-- 1 spider spider 0 Feb 11 14:24 stats.log drwxr-xr-x 2 root other 512 Feb 9 16:36 util
# ls -l /usr/local/etc/qstatlist/lib -rw-r--r-- 1 root other 5608 Feb 11 11:08 dns.pl -rw-r--r-- 1 root other 10487 Feb 11 11:08 domains.pl -rw-r--r-- 1 root other 22622 Feb 11 11:08 html.pl -rw-r--r-- 1 root other 9007 Feb 11 11:08 maps.pl -rw-r--r-- 1 root other 25186 Feb 11 11:08 stats.pl
# ls -l /usr/local/etc/qstatlist/util -rwxr--r-- 1 root other 2931 Feb 15 10:29 listbak.pl -rwxr--r-- 1 root other 8194 Feb 15 10:43 statssum.pl
You should now be ready to run qstatlist for the first time to generate the base HTML output. Proceed to the next section, Running QstatList.
The qstatlist Perl script is the QstatList component that actually performs the QStat queries and generates the HTML pages that comprise the list.
IMPORTANT: The CGI scripts that comprise the rest of the QstatList package will not operate properly until qstatlist has been run at least once successfully as the cron user. This generates the required output data (with the proper ownership and permissions) that these programs read. It's perfectly acceptable to run qstatlist with an empty (but extant) list.dat, as qstatlist will merely generate the appropriate empty page placeholders. See Automating the QstatList Process for information on how to do this and set up the automated process.
The list.dat Format
A typical list.dat file might contain entries like the following:
H2S 205.250.240.14:26900 888280806 Canada H2S 24.0.185.80:26900 888804605 California, USA H2S 24.108.19.133:26900 883968005 Canada Q2 128.164.141.3:27910 0 The George Washington University, Washington, DC, USA Q2 149.159.11.70:27910 887955617 Indiana, USA Q2 171.64.187.67:27910 0 Educational Q2 192.246.40.37:27910 0 id Software, Mesquite, TX, USA Q2 192.246.40.37:27911 0 id Software, Mesquite, TX, USA Q2 192.246.40.37:27912 0 id Software, Mesquite, TX, USA QS 128.164.136.171:26000 882972649 Washington, DC, USA QS 128.164.141.5:26000 0 Washington, DC, USA QS 128.83.50.122:26000 887301607 Austin, TX, USA QS 149.106.37.197:26000 888728406 Schenectady, NY, USA QS 198.161.102.18:26000 0 Red Deer, Alberta, Canada QWM 192.246.40.12:27000 0 id Software Main, Mesquite, TX, USA QWM 192.246.40.12:27002 0 id Software CTF, Mesquite, TX, USA QWM 192.246.40.12:27003 0 id Software TF, Mesquite, TX, USA QWM 192.246.40.12:27004 0 id Software Misc, Mesquite, TX, USAThe file is stored in standard UNIX ASCII text, with columns delimited by one or more spaces. Case is significant, and there is one entry per line (entries may not span lines).
The first column is the server type and may have one of the following values:
- H2S - Hexen II Server
- HLS - Half-Life Server
- HWS - HexenWorld Server
- Q2 - Quake II Server
- Q2M - Quake II Master Server
- QS - Plain Old Quake Server
- QW - QuakeWorld Server
- QWM - QuakeWorld Master Server
- SNS - Sin Server
- UNS - Unreal Server
The second column consists of the server IP address in dotted decimal notation followed by a colon (:) and the port number of the server.
The third column is the time that the server first failed to respond. This value will be the value returned by time() (number of non-leap seconds since the epoch). A responsive server will set this field to a value of zero (0).
The fourth column is a string containing the location of the server (city, state, country).
The list.dat is typically maintained through qstatlist. The addqserver CGI program uses hold.dat as a "dropbox" for the qstatlist program to pick up new entires from. New servers may be added using a forms-based interface through addqserver, which will solicit the required information from the user and validate the new entry before adding it to the list. Severs which have been continuously unresponsive (the difference between the current time and the value in the third column of the server's entry) has exceeded the $TIMEOUT value in the qstatlist.conf file. Both addqserver and qstatlist track server additions and deletions using list.log, the QstatList log file.
Automating the QstatList Process
Before setting cron loose with qstatlist, check to make sure that qstatlist can execute quietly. Either as the qstatlist user ('su - spider' to become the user 'spider' with the environment set to what would be expected if the user actually logged in as the 'spider' user) or using the setuid bit on qstatlist, execute the "compiled" version of qstatlist by typing './qstatlist'. If it executes without generating any console output, and the HTML output in the $LIST_BASEDIR directory looks fine, go on to the next step. Otherwise, take appropriate action. Most of your problems will result from improper file permissions or ownership.
Create a crontab entry for the user that will be running qstatlist:
0,10,20,30,40,50 * * * * <full path to qstatlist>This will run qstatlist once every ten minutes.
WARNING: Keep in mind that most cron implementations send any program output back to the cron user in the form of an e-mail message. If something goes wrong, and qstatlist starts generating output, cron will mail one message for each run which generates output. While qstatlist does not normally generate output except in cases of fatal errors, this can compound a problem by very easily filling up a mail partition. In general, it is a good idea to keep your mail partition on a separate filesystem.
Test access to the list using the $URL_BASE URL. It should (using the symbolic link index.html) return the listing for the $DODEFAULT server type (by default, Quake Servers).
If all is well, you may use $URL_BASE (or any of the *-1.html files) as the entry point into your list(s).
Once installed, QstatList is fairly easy to maintain. In order to protect your system integrity, keep track of the size of the files that QstatList generates. The logs, server database, and output HTML files are essentially of unbounded length and can become unwieldy or detrimental to system performance should they be allowed to take up excessive amounts of space. Also keep in mind that each qstatlist run produces a large number of qstat requests which can hinder local network performance as well as bog down the remote Quake sites that are responding to the queries. For this reason, the interval between qstatlist runs should be of some moderate length (five minutes or more is a good value).
QstatList deals with dates in UN*X time format (seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time) and writes to the logs in 4-digit year format. Thus, it should not have problems with the year 2000. Note however, that QstatList comes with NO WARRANTY.
Note that most (if not all) current Perl UN*X implementations will have problems when time_t turns over on January 19, 2038. This is not, however, a QstatList bug.
If you experience difficulties with QstatList, or have comments or questions, please contact the author, Dark Grue, at darkgrue@iname.com.
QUAKE is a registered trademark of id Software, Inc.
QStat is
copyright Steve Jankowski <steve@activesw.com>.
Copyright © 1999, Dark Grue <darkgrue@iname.com>.