QstatList Logo Installation and Use


Availability

The QstatList package is available as a gzipped tar file, containing the source and documentation files.

The package is available via FTP from:


System Requirements

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.


Installation

  1. First, uncompress the QstatList distribution using gunzip:
    gunzip qstatlist-x.x.tar
    Where 'x.x' is the package version number. Next, un-tar the file by typing:
    tar -xfv qstatlist-x.x.tar
    Again, where 'x.x' is the package version number. This will create a subdirectory './qstatlist-x.x' and populate it with the tar file contents.
  2. Create a user that will run qstatlist as a cron job. This may be root, an existing user, or one created specially for this purpose. While qstatlist should be able to run as root safely, it is *not* recommended. Instead, create a unique user and group (such as 'spider' and 'spider') to be used solely for the purpose of running cron jobs on behalf of the Web server. Do not give membership in this user's group to any other account! This account should not allow logins, and should be given only enough access to run the scripts and access the data files.

Assisted Install

  1. Optionally, edit qstatlist.conf and/or ./src/qstatlist.src to change the behavior of QstatList (see the Manual Install section for some of the more common options). The defaults should be sufficient for most installations however.
  2. Execute the install utility by typing:
    <full path to perl> install.pl
    and 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.

Manual Install

  1. Configure the QstatList package by editing qstatlist.conf: Once you are finished editing qstatlist.conf, copy it to the $QSTATLIST_BASEDIR directory and set the file permissions to 0644 (-rw-r--r--). [This file must be readable by at least the cron user and the Web server's CGI user.]
  2. Edit the variables section of qstatlist.src, which you copied to $QSTATLIST_BASEDIR in Step 3:
  3. "Compile" qstatlist.src by executing:
    grep -v "# debug" qstatlist.src > qstatlist
    This removes the debugging output from the source. At this point you may wish to delete the qstatlist.src file.
  4. Set the file permissions of qstatlist to 04700 (-rws------) or 04744 (-rwsr--r--). (Making qstatlist setuid allows the ownership of files created by the scripts to be set properly regardless of which user kicked off the run.) Give ownership of qstatlist to the cron user set up in Step 2and set the group appropriately. If you do not wish to run qstatlist setuid, set the file permissions of qstatlist to 0700 (-rwx------) or 0744 (-rwxr--r--).
  5. Copy addqserver.src and qstatwrap.src from the distribution cgi-src/ directory to the Web server CGI-bin directory (on Netscape servers, this would typically be /usr/ns-home/cgi-bin or /usr/netscape/suitespot/cgi-bin). By default, the CGI scripts are placed in a qstatlist/ subdirectory.
  6. Edit the variables section of addqserver.src:
  7. "Compile" addqserver.src by executing:
    grep -v "# debug" addqserver.src > addqserver.cgi
    This removes the debugging output from the source.
  8. Edit the variables section of qstatwrap.src:
  9. "Compile" qstatwrap.src by executing:
    grep -v "# debug" qstatwrap.src > qstatwrap.cgi
    This removes the debugging output from the source.
  10. Set the file permissions of addqserver.cgi, qservers.cgi, and qstatwrap.cgito 0755 (-rwxr-x-r-x). [This file must be executable by at least the cron user.]
  11. At this time, you may wish to remove the addqserver.src and qstatwrap.src files.

Checkpoint

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.


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, USA

The 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:

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 and the Year 2000

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.


Contacting the Author

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>.