NAME

qstat - Get statistics from on-line game servers

SYNOPSIS

qstat [options ...] [-f file] [-of|-af output-file] [-server-option host[:port]]
[-raw delimiter] [-default server-type] host[:port] ...

Version 2.5b

DESCRIPTION

QStat is a command-line program that displays information about Internet game servers. The servers are either down, non-responsive, or running a game. For servers running a game, the server name, map name, current number of players, and response time are displayed. Server rules and player information may also be displayed.

Games supported include Quake, QuakeWorld, Hexen II, Quake II, HexenWorld, Unreal, Half-Life, Sin, Shogo, Tribes, Tribes 2, Quake III: Arena, BFRIS, Kingpin, and Heretic II, Unreal Tournament, Soldier of Fortune, Rogue Spear, Redline, Turok II, Blood 2, Descent 3, Drakan, KISS, Nerf Arena Blast, Rally Master, Terminous, Wheel of Time, and Daikatana. Note for Tribes 2: QStat only supports Tribes 2 builds numbered 22075 or higher.

Some games use query protocols compatible with an existing game. These servers can be queried using the flags for the compatible game. For instance, Turok2 should work using the -uns flag. Unreal Tournament is also supported by the -uns but is not really a different game. You can distinguish Unreal Tournament games with the "minnetver" server rule (standard Unreal servers have a "mingamever" server rule).

The Quake servers can be divided into two categories: POQS (Plain Old Quake Server) and QuakeWorld. Quake shareware, Quake commercial (from CD), winquake, winded, unixded, and Hexen II are all POQS. The various versions of QuakeWorld and Quake II use a QuakeWorld type server. The distinction is based on network protocol used to query the servers, and affects the kind of information available for display.

The different server types can be queried simultaneously. If QStat detects that this is being done, the output is keyed by the type of server being displayed. See DISPLAY OPTIONS.

The game server may be specified as an IP address or a hostname. Servers can be listed on the command-line or, with the use of the -f option, a text file.

DISPLAY MODES

One line will be displayed for each server queried. The first component of the line will be the server's address as given on the command-line or the file. This can be used as a key to match input addresses to server status. Server rules and player information are displayed under the server info, indented by one tab stop.

QStat supports three additional display modes: raw, templates, and XML. In raw mode, the server information is displayed using simple delimiters and no formatting. This mode is good for programs that parse and reformat QStat's output. The template mode uses text files to layout the server information within existing text. This is ideal for generating web pages. The XML mode outputs server information wrapped in simple XML tags. The raw mode is enabled using the -raw option, template output is enabled using -Ts, and XML output is enabled with -xml.

GAME OPTIONS

These options select which servers to query and what game type they are running. Servers are specified by IP address (for example: 199.2.18.4) or hostname. Servers can be listed on the command-line or in a file (see option -f.) The game type of a server can be specified with its address, or a default game type can be set for all addresses that don't have a game type.

The following table shows the command-line option and type strings for the supported game types. The type string is used with the -default option and in files with the -f option.

OptionType StringDefault PortGame Server
-qsqs26000Quake
-h2sh2s26900Hexen II
-qwsqws27500QuakeWorld
-hwshws26950HexenWorld
-q2sq2s27910Quake II
-unsuns7777Unreal
-hlshls27015Half-Life
-snssns22450Sin
-sgssgs27888Shogo: Mobile Armor Division
-tbstbs28001Starsiege: Tribes
-t2st2s28000Tribes 2
-qwmqwm27000QuakeWorld master
-q2mq2m27900Quake II master
-hlmhlm27010Half-Life master
-tbmtbm28000Tribes master
-t2mt2m28002Tribes 2 master
-q3sq3s27960Quake III
-q3mq3m27950Quake III master
-bfsbfs44001BFRIS
-kpskps31510Kingpin
-hrshrs28910Heretic II
-sfssfs28910Soldier of Fortune
-gsmgsm28900Gamespy master
-gpsgps-Game using "Gamespy style" protocol
-d3md3m3445Descent 3 PXO master
-d3pd3p2092Descent 3, PXO server
-d3sd3s2092Descent 3, LAN server
-d3gd3g20142Descent 3, Gamespy protocol
-rwsrws27960Return to Castle Wolfestein
-rwmrwm27950Return to Castle Wolfestein master
-efsefs27960Star Trek: Elite Force
-efmefm27953Star Trek: Elite Force master

The command-line options can be specified multiple times, one for each server to be queried.

Configuration Files

The games supported by QStat can be customized with configuration files. The query parameters of built-in game types can be modified and new games can be defined.

For built-in game types, certain parameters can be modified. The parameters are limited to the master server protocol and master server query string.

New game types can be defined as a variation on an existing game type. Most new games use a Quake 3 or Gamespy/Unreal based network engine. These games can already be queried using -q3s or -gps, but they don't have game specific details such as the correct default port, the game name, and the correct "game" or "mod" server rule. And, mostly importantly, they don't get their own game type string (e.g. q3s, rws, t2s). All of these details can be specified in the QStat config file.

QStat comes with a default configuration file called 'qstat.cfg'. If this file is found in the directory where qstat is run, the file will be loaded. Configuration files can also be specified with the QSTAT_CONFIG environment variable and the -cfg command-line option. See Appendix B for a description of the configuration file format.

Descent 3

Support for Descent 3 is a bit fragmented. There are three different protocols for getting status information from a Descent 3 server: PXO, LAN, and Gamespy. If the server was acquired from the PXO master server, then the PXO protocol is used. If the server is running on the local LAN (not reporting to a master server), then the LAN protocol should be used. Finally, if the server's Gamespy query port is known (default is 20142) then the Gamespy protcol can be used. The gamespy protocol can be used on servers listed in the PXO master.

Each protocol reports different information. The Gamespy protocol provides player names, frags, deaths, and ping. The PXO and LAN protocols only provide player names.

The ideal solution would be a PXO server list paired with each server's gamespy query port. Most servers will use the default gamespy query port, unless there are multiple servers on the same machine. A possible approach is to get the server list from the PXO master like this:

qstat -d3m,outfile gt.pxo.net,d3pxo.txt
Then convert the file from "d3p" to "d3g" and remove the port numbers:
sed -e 's/d3p/d3g/' -e 's/:.*$//' d3pxo.txt > d3gs.txt
Then run the servers in d3gs.txt with -f:
qstat -f d3gs.txt
This technique will retrieve the full player info for servers using the default gamespy query port.

Broadcast Queries

QStat has limited support for broadcast queries. Broadcast queries use one network packet to find all the game servers on a local network. A broadcast returns servers of one type on one port. You may only broadcast to networks to which you computer is directly attached (ie. local networks). In this release, broadcast queries are only supported for: Quake II servers and Gamespy style servers.

A broadcast query is specified by prefixing an address with a '+' (plus sign). The address should be 255.255.255.255 or a valid broadcast address for your local network. On Unixes, 'ifconfig -a' will display the broadcast address for all attached networks.

Master Servers

Master server addresses don't change very often, but some times they go off-line. The following is a table of some of the master servers I know about.

GameMaster Servers
QuakeWorldsatan.idsoftware.com (ports 27000, 27002, 27003, 27004, 27006), 204.182.161.2, 194.217.251.40, 203.34.140.1, 200.245.221.200, 194.87.251.3
Quake IIsatan.idsoftware.com, q2master.planetquake.com
Half-Lifehalf-life.west.won.net, half-life.east.won.net
Tribestribes.dynamix.com
Quake IIImaster3.idsoftware.com
Gamespymaster0.gamespy.com
Tribes 2211.233.32.77:28002, 217.6.160.205:28002
Descent 3gt.pxo.net
Return to Castle Wolfensteinwolfmaster.idsoftware.com
Star Trek: Elite Forcemaster.stef1.ravensoft.com

Gamespy Master

Access to the gamespy masters has been disabled by Gamespy Inc.

Server lists can be fetched from Gamespy masters by using the gsm game type. A query argument is required to use the Gamespy master. This extra argument indicates which server list to get from the master. The query argument can be one of the QStat supported game types or any other string that will fetch a server list. The following game types can be used as query arguments: qws, q2s, q3s, tbs, uns, sgs, hls, kps, hrs, sfs. For each of the game types, QStat will fetch the appropriate server list and get status from each server.

The query argument can also be any string that the Gamespy master responds to. Most of these games support a "standard" server status protocol that I'll call the "Gamespy status protocol". Not surprisingly, it is almost identical to the Unreal server status protocol. This means that QStat can support any game that supports this protocol. In QStat these games are queried using the gps game type. Through experimentation I've found the following query arguments.

Query ArgumentGame
roguespearRainbow Six: Rogue Spear
redlineRedline Racer
turok2Turok 2: Seeds of Evil
blood2Blood 2: The Chosen
drakanDrakan: Order of the Flame
kissKISS Psycho Circus: The Nightmare Child
nerfarenaNerf Arena Blast
rallyRally Masters: Michelin Race Of Champions
terminousTerminous (?)
wotThe Wheel of Time
daikatanaDaikatana

Tribes 2 Master

The Tribes 2 master server supports a number of filtering options. You can set these filters with QStat by appending query arguments to the server type. The general syntax is:
t2m,query-arg=value, ...
Query ArgumentValuesDescription
gamemod pathMod path the server is using. The mod path of unaltered servers is "base". Use query=types to get the list of known game types.
missionBounty, Capture the Flag, CnH, Deathmatch, Hunters, Rabbit, Siege, TeamHuntersMission type the server is currently running. Use query=types to get the list of known mission types.
minplayers0 - 255Servers with fewer players than this will not be returned.
maxplayers1 - 255Servers with more players than this will not be returned.
regionslist of regions or 0xhex-value Limit servers to those in the given geographical regions. See Region List table. The regionlist is sent as a bit mask to the Tribes 2 master. If you know the bit mask for a region QStat doesn't support, you can specify the bitmask directly by supplying a hex value: regions=0x11.
buildbuild version # Only return servers matching this build version number. [4/20/2001] This filter only seems to work if the build version # is 22337. If the filter is 22228, then the master returns 0 servers. This appears to be a bug in the T2 master.
statuslist of dedicated, linux, nopassword
or 0xhex-value
Limit servers to those with these status flags set. The list is one or more status flags separated by colons (':'). To filter on dedicated Linux servers, specify status=dedicated:linux
If you know a status flag that QStat doesn't support, you can specify the status flags directly by supplying a hex value: status=0x3
maxbots0 - 255Servers with more bots than this will not be returned.
mincpu0 - 65535Servers with lower CPU speed than this will not be returned.
querytypesGet the list of game and mission types. This is not a filter but a different master request. Using this query argument overrides any other query arguments. The list of game and mission types known to the master server will be displayed. In raw mode, the first line is the list of game types and the second line is the list of mission types. There is no output template support for game and mission lists.
Region List
The region list is one or more region arguments separated by colons (':'). For example, to filter on North American servers specify regions=naeast:nawest

Region ArgumentGeography
naeastNorth America East
nawestNorth America West
saSouth America
ausAustralia
asiaAsia
eurEurope

The Tribes 2 master query arguments can be used on the command-line or in a server list file (via the -f option). If the values contain spaces, be sure to quote the arguments for your shell. The second example below demonstrates this usage for most common shells. To query for Capture the Flag servers that have more than 6 players:
qstat -t2m,mission=Capture the Flag,minplayers=6 master-server-ip
qstat -t2m,mission="Capture the Flag",minplayers=6 master-server-ip
If you want to do this in a server list file, that would look like this:
t2m,mission=Capture the Flag,minplayers=6 master-server-ip
Master server filters can be combined with the "outfile" option. Just put outfile some where in the query argument list and put the name of the output file after the master IP address:
t2m,outfile,mission=Siege,minplayers=4 master-server-ip,siegeservers.txt
Warning: There is a bug in the 22075 build of Tribes 2 that doesn't return the game name. For those builds, QStat will use the game info in place of the game name. The bug is fixed in the 22228 build. In fixed servers, the game info can be found in the "info" server rule.

Half-Life Master

The Half-Like master server supports a number of filtering options. You can set these filters with QStat by appending query arguments to the server type. The general syntax is:
hlm,query-arg=value, ...
Query ArgumentValuesDescription
gamemod pathServers running this "mod".
mapmap nameServers running this map.
statuslist of dedicated, linux, notempty, notfull Limit servers to those matching this status. The list is one or more status flags separated by colons (':'). To filter on dedicated servers that are not empty, specify status=dedicated:notempty
See the Tribes 2 master server above for example usage.

Option Usage

-cfg configuration-file
Load the QStat configuration file. New game types defined in the config file can be used in subsequent command-line options.
-server-option host[:port]
Query game server host for status. The GAME OPTIONS table lists the available server-options and their default port.
-nocfg Ignore qstat configuration loaded from any default location (see Appendix B for a list of default locations). Must be the first option on the command-line. Use this option to have complete control over the configured game types.
-master-server-option host[:port]
Query a game master for its server list and then query all the servers. The GAME OPTIONS table lists the available master-server-options and their default port.
-master-server-option,outfile host[:port],file
Query a game master for its server list and store it in file. If the master cannot be contacted, then file is not changed. If file is - (a single dash), then stdout is used. The GAME OPTIONS table lists the available master-server-options and their default port.
-gsm,query-argument host[:port]
Query a Gamespy master for a server list and then query all the servers. The Gamespy Master section details the supported values for query-argument.
-gsm,query-argument,outfile host[:port],file
Query a Gamespy master for a server list and store it in file. If the master cannot be contacted, then file is not changed. If file is - (a single dash), then stdout is used. The Gamespy Master section details the supported values for query-argument.
-q3m,query-argument host[:port]
Query a Quake 3 Arena master for a protocol-specific server list and then query all the servers. The query-argument should be a Quake 3 protocol version. Protocol version 48 is Quake 3 version 1.27, protocol 46 is Quake 3 version 1.25, protocol 45 is Quake 3 1.17, protocol 43 is Quake 3 version 1.11. The default is protocol version 48.
-q3m,query-argument,outfile host[:port],file
Query a Quake 3 Arena master for a protocol-specific server list and store it in file. The query-argument should be a Quake 3 protocol version. Protocol version 46 is Quake 3 version 1.25, protocol 45 is Quake 3 1.17, protocol 43 is Quake 3 version 1.11. The default is protocol version 45.
-f file
Read host addresses from the given file. If file is -, then read from stdin. Multiple -f options may be used. The file should contain host names or IP addresses separated by white-space (tabs, new-lines, spaces, etc). If an address is preceded by a server type string, then QStat queries the address according to the server type. Otherwise QS is assumed, unless -default is used. The GAME OPTIONS table lists the available server type strings and their default port.
-default type-string
Set the default server type for addresses where the type is not obvious. This affects the addresses at the end of the qstat command-line and those in a file not prefixed by a server type (see -f). The GAME OPTIONS table lists the available server type strings and their default port.

INFO OPTIONS

-R
Fetch and display server rules.
-P
Fetch and display player information.

DISPLAY OPTIONS

The QStat output should be self explanatory. However, the type of information returned is different between game types. If QStat queries multiple server types, then each server status line is prefixed with its type string. The GAME OPTIONS table lists the available type strings.

-of file
Write output to file instead of stdout or the console. file is over written if it already exists.
-af file
Like -of, but append to the file. If file does not exist, it is created.
-u
Only display hosts that are up and running a game server. Does not affect template output.
-nf
Do not display full servers. Does not affect template output.
-ne
Do not display empty servers. Does not affect template output.
-nh
Do not display header line (does not apply to raw or template output.)
-cn
Display color names instead of numbers. This is the default. Only applies to Quake, QuakeWorld, Hexen II, and HexenWorld.
-ncn
Display color numbers instead of color names. This is the default for -raw mode. Only applies to Quake, QuakeWorld, Hexen II, and HexenWorld.
-hc
Display colors in #rrggbb format. This is nice for HTML output. Only applies to Quake, QuakeWorld, Hexen II, and HexenWorld.
-tc
Display time in clock format (DhDDmDDs). This is the default.
-tsw
Display time in stop-watch format (DD:DD:DD).
-ts
Display time in seconds. This is the default for -raw mode.
-pa
Display player addresses. This is the default for -raw mode. Only available for Quake and Hexen II.
-sort sort-keys
Sort servers and/or players. Servers and players are sorted according to sort-keys. Lower case sort keys are for servers and upper case keys are for players. The following sort keys are supported:
  • p - Sort by ping
  • g - Sort by game (mod)
  • i - Sort by IP address
  • h - Sort by hostname
  • n - Sort by number of players
  • l - Sort by list order
  • P - Sort by player ping
  • F - Sort by frags
  • T - Sort by team

The 'l' (ell) sort key displays servers in the order they were provided to qstat. For example, the order in which they are listed on the command-line or in a file. The 'l' sort key cannot be combined with other server sort keys, but it can be be combined with player sort keys. If the 'l' sort key is used with other sort keys, then the 'l' sort key is ignored.

-hpn
Display player names in hex.
-old
Use pre-qstat 1.5 display style.
-raw delimiter
Display data in "raw" mode. The argument to -raw is used to separate columns of information. All information returned by the game server is displayed.
POQS output -- General server information is displayed in this order: command-line arg (IP address or host name), server name, server address (as returned by Quake server), protocol version, map name, maximum players, current players, average response time, number of retries. Server rules are displayed on one line as rule-name=value. If significant packet loss occurs, rules may be missing. Missing rules are indicated by a "?" as the last rule. Player information is displayed one per line: player number, player name, player address, frags, connect time, shirt color, pants color. A blank line separates each set of server information.
QuakeWorld and HexenWorld server output -- General server information is displayed in this order: command-line arg (IP address or host name), server name, map name, maximum players, current players, average response time, number of retries, game (mod). Server rules are displayed on one line as rule-name=value. Player information is displayed one per line: player number, player name, frags, connect time, shirt color, pants color, ping time (milliseconds), skin name. A blank line separates each set of server information.
All master server output -- Master server information is displayed in this order: command-line arg (IP address or host name), number of servers. No other information is displayed about master servers.
Quake II, Quake III, Half-Life, Sin, BFRIS, Kingpin, Heretic II, Unreal, Tribes 2, and Shogo server output -- General server information and server rules are the same as a QuakeWorld server. The player information varies for each game:
  • Quake II/III, Sin, Kingpin, Heretic II, Shogo: player name, frags, ping time
  • Half-Life: player name, frags, connect time
  • Tribes: player name, frags, ping time, team number, packet loss
  • Tribes 2: player name, frags, team number, team name, player type, tribe tag
  • Unreal: player name, frags, ping time, team number, skin, mesh, face
  • BFRIS: player number, ship, team name, ping time, score, frags, player name
  • Descent 3: player name, frags, deaths, ping time, team
Ping time is in milli-seconds. Connect time is in seconds. A blank line separates each set of server information.

Servers queried using the "Gamespy style" protocol use the same raw output format as Unreal servers.

-raw,game delimiter
Same as -raw but adds the game or mod name as the last item of server info.
-raw-arg
When used with -raw, always display the server address as it appeared in a file or on the command-line. Note that when -H is used with -raw, the first field of the raw output could be a hostname if the server IP address was resolved. This can make matching up input servers addresses with raw output lines fairly difficult. When -raw-arg is also used, an additional field, the unresolved server address, is added at the beginning of all raw output lines.
-progress
Print a progress meter. Displays total servers processed, including timeouts and down servers. The meter is just a line of text that writes over itself with <cr>. Handy for interactive use when you are redirecting output to a file (the meter is printed on stderr).
-Tserver file
-Tplayer file
-Trule file
-Theader file
-Ttrailer file
Output templates. Each template should be a text file containing QStat variables that are substituted for results from the server query. The -Tserver flag must present to enable template output. The other -T flags are optional. The server template is output once for each server queried. The player template, if present, is output once for each player (if -P is also used). The rule template is output once for each server rule (the -R option may be required for some game types). The header template is output once before any servers are output. The trailer template is output once after all servers are output. See Appendix A for the output template formatting and variables.
NOTE: All of of the -T flags may be abbreviated with two characters: -Ts, -Tp, -Tr, -Th, and -Tt.
-htmlnames
Colorize Quake 3 and Tribes 2 player names using html font tags. Enabled by default if $HTML is used in an output template.
-nohtmlnames
Do not colorize Quake 3 and Tribes 2 player names even if $HTML is used in an output template. The $HTMLPLAYERNAME variable will always colorize player names.
-htmlmode
Convert <, >, and & to the equivalent HTML entities. This is the same as $HTML in an output template, but works for raw display mode. Using -htmlmode with -xml will result in double-escaping.
-carets
Display carets in Quake 3 player names. Carets are used for colorized player names and are remove by default. This option has no effect if -htmlnames is enabled.
-xml
Output server information wrapped in XML tags.
-utf8
Use the UTF-8 character encoding for XML output.
-errors
Display errors.
-d
Enable debug options. By default, enables printing of all received packets to stderr.

SEARCH OPTIONS

-H
Resolve IP addresses to host names. Use with caution as many game servers do not have registered host names. QStat may take up to a minute to timeout on each unregistered IP address. The duration of the timeout is controlled by your operating system. Names are resolved before attempting to query any servers.
-Hcache cache-file
Cache host name and IP address resolutions in cache-file. If the file does not exist, it is created. If -Hcache is used without -H, then the cache is only used for host to IP address resolution. WARNING A host cache file should not be shared by QStat programs running at the same time. If you run several QStats at the same time, each should have its own cache file.
-interval seconds
Interval in seconds between server retries. Specify as a floating point number. Default interval is 0.5 seconds. This option does not apply to master servers (see -mi.)
-mi seconds
Interval in seconds between master server retries. Specify as a floating point number. Default interval is 2 seconds.
-retry number
Number of retries. QStat will send this many packets to a host before considering it non-responsive. Default is 3 retries.
-maxsimultaneous number
Number of simultaneous servers to query. Unix systems have an operating system imposed limit on the number of open sockets per process. This limit varies between 32 and 100 depending on the platform. On Windows 95 and Windows NT, the "select" winsock function limits the number of simultaneous queries to 64. These limits can be increased by minor changes to the code, but the change is different for each platform. Default is 20 simultaneous queries. This option may be abbreviated -maxsim.
-timeout seconds
Total run time in seconds before giving up. Default is no timeout.

NETWORK OPTIONS

-srcport port-number | port-range
Specify the source ports for sending packets. The ports can be a single number or a range. A range is two numbers separated by a dash ('-'). The numbers should be positive and less than 65535. Use this option to get through a firewall that has source port restrictions. Set -srcport to the range of ports allowed by the firewall.

Example: If your firewall will allow outgoing UDP packets on ports 26000-30000, the qstat option would be -srcport 26000-30000

Note: The number of source ports given should be greater than or equal to the -maxsim (defaults to 20). The number of source ports will limit the number of simultaneous server queries.

-srcip IP-address
Specify a local IP address from which to send packets. This is useful on machines that have multiple IP addresses where the source IP of a packet is checked by the receiver. Normally this option is never needed.

NOTES

The response time is a measure of the expected playability of the server. The first number is the server's average time in milli-seconds to respond to a request packet from QStat. The second number is the total number of retries required to fetch the displayed information. More retries will cause the average response time to be higher. The response time will be more accurate if more requests are made to the server. For POQS, a request is made for each server rule and line of player information. So setting the -P and -R options will result in a more accurate response time. Quake and Hexen II are POQS. For most other game servers, QStat makes just one request to retrieve all the server status information, including server rules and player status. The -P and -R options do not increase the number of requests to the server. Half-Life supports three different requests for information; general status, players, and server rules. Each requires a separate request packet, so a total of three are used to retrieve player and rules.

Quake supports a number of control codes for special effects in player names. QStat normalizes the codes into the ASCII character set before display. The graphic codes are not translated except the orange brackets (hex 90, 10, 91, and 11) which are converted to '[' and ']'. Use the hex-player-names option -hpn to see the complete player name.

POQS do not return version information. But some small amount of info can be gathered from the server rules. The noexit rule did not appear until version 1.01. The Quake II server rules include a "version" key that contains the id build number. Recent releases of QuakeWorld have a "*version" key in the server rules. Unreal servers include a "gamever" key in the server rules that contains the server version without the decimal point. Most other game servers include some kind of version info in the server rules.

EXAMPLES

The following is an example address file that queries a QuakeWorld master, several Hexen II servers, some POQS, and a few Quake II servers.

QWM 192.246.40.12:27004
H2S 207.120.210.4
H2S 204.145.225.124
H2S 207.224.190.21
H2S 165.166.140.154
H2S 203.25.60.3
QS 207.25.198.110
QS 206.154.207.104
QS 205.246.42.31
QS 128.164.136.171
Q2S sm.iquest.net
Q2S 209.39.134.5
Q2S 209.39.134.3

If the above text were in a file called QSERVER.TXT, then the servers could be queried by running:
qstat -f QSERVER.TXT

IMPLEMENTATION NOTES

QStat sends packets to each host and waits for return packets. After some interval, another packet is sent to each host which has not yet responded. This is done several times before the host is considered non-responsive. QStat can wait for responses from up to 20 hosts at a time. For host lists longer than that, QStat checks more hosts as results are determined.

The following applies only applies to POQS. If QStat exceeds the maximum number of retries when fetching server information, it will give up and try to move on to the next information. This means that some rules or player info may occasionally not appear. Player info may also be missing if a player drops out between getting the general server info and requesting the player info. If QStat times out on one rule request, no further rules can be fetched. This is a side-effect of the Quake protocol design.

The number of available file descriptors limits the number of simultaneous servers that can be checked. QStat reuses file descriptors so it can never run out. The macro MAXFD in qstat.c determines how many file descriptors will be simultaneously opened. Raise or lower this value as needed. The default is 20 file descriptors.

Operating systems which translate ICMP Bad Port (ICMP_PORT_UNREACHABLE) into a ECONNREFUSED will display some hosts as DOWN. These hosts are up and connected to the network, but there is no program on the port. Solaris 2.5 and Irix 5.3 correctly support ICMP_PORT_UNREACHABLE, but Solaris 2.4 does not. See page 442 of "Unix Network Programming" by Richard Stevens for a description of this ICMP behavior.

Operating systems without correct ICMP behavior will just report hosts without Quake servers as non-responsive. Windows NT and Windows 95 don't seem to support this ICMP.

For hosts with multiple IP addresses, QStat will only send packets to the first address returned from the name service.

QStat supports Unreal version 2.15 or greater.

BUGS

PORTABILITY

UNIX - QStat has been compiled and tested on Solaris 2.x, Irix 5.3/6.2/6.3/6.4, FreeBSD 2.2/3.0, BSDi, HP-UX 10.20/11.0, and various flavors of Linux.

WINDOWS - The Windows version of QStat (win32/qstat.exe) runs on Windows 95 and Windows NT as a console application. On Windows 95 and NT 4.0, short-cuts can be used to set the arguments to qstat. On Windows NT 3.51, use a batch file.

OS/2 - An OS/2 binary is no longer included. Try contacting Per Hammer for an OS/2 Warp binary. per@mindbend.demon.co.uk.

VMS - The source includes a VMS patch from John Ross Hunt. This patch was tested on QStat 2.0b, but has not been tested on the current version. See COMPILE.txt for instructions.

VERSION

This is QStat version 2.5b. The QStat webpage is updated for each new version and contains links to Quake server listings and pages about the Quake and Unreal network protocols. The page can be found at
http://www.qstat.org

Quake, Quake II, QuakeWorld, and Quake III created by id Software. Hexen II, HexenWorld, and Heretic II created by Raven Software. Unreal created by Epic Games. Half-Life created by Valve Software. Sin created by Ritual Entertainment. Shogo: Mobile Armor Division was created by Monolith Productions Inc. Tribes and Tribes 2 created by Dynamix, Inc. BFRIS created by Aegis Simulation Technologies. Kingpin created by Xatrix Entertainment Inc.

AUTHOR

Steve Jankowski
steve@qstat.org

COPYRIGHT

Copyright © 1996,1997,1998,1999 by Steve Jankowski

LICENSE

QStat is covered by the terms of the Artistic License. The license terms can be found in LICENSE.txt of the QStat package.


APPENDIX A - Output Templates

QStat output templates provide greater control of the appearance of server status information. The results of a server query can be organized, formatted, and wrapped within any other text. The most obvious use is to generate HTML for web pages. However, it could also generate custom output for redisplay within another tool.

There are four output templates:
TemplateOption 
server-TsOutput once for each server queried. (required)
player-TpOutput once for each player. Must be used with -P. Invoked by the $PLAYERTEMPLATE variable.
player-TrOutput once for each server rule. Invoked by the $RULETEMPLATE variable.
header-ThOutput once before any servers are queried.
trailer-TtOutput once after all servers are output.

The server template must be specified to enable template output. The other templates are optional.

Each output template is a file containing text and QStat variables. The text is output unchanged by QStat, but the variables are processed and replaced by QStat. Most variables are replaced by values from a queried server. Some variables have hardcoded values, and some generate no output, but affect how the template is processed.

Variables are grouped according to the templates where they can be used. General variables may be used in any of the templates. Server variables may be used in the server or player templates. Player variables may be used in the player template. Expression variables may only be used with the $IF and $IFNOT variables. If a variable is used where it doesn't make sense, it is ignored and generates no output.

Variables are specified using one of several syntaxes:

    $VAR
    $VAR:OPTION
    $(VAR)
    $(VAR:OPTION)
    $(VAR:OPTION(ARGUMENT))
The syntax used does not affect the output. However using the $() syntax is somewhat more readable when the text gets cluttered. If you want the variable to be followed immediately by text, then the $() syntax must be used.

Download considerations

If you are generating output to be downloaded, then you'll want to make your output as small as possible. In the case of HTML, you can reduce the size of your pages by excluding stuff.
  • Remove unneeded spaces (indenting and newlines)
  • Remove unneeded end tags. The HTML spec says the following tags can always be left out: </TD> </TR> </TH>
  • When creating a table, "width" modifiers are only needed on one cell of a column. Put them on the cells of the first row of the table.

    Display options

    The display options -u, -ne, and -nf have no affect on template output. Use the $IF:UP, $IF:ISEMPTY, and $IF:ISFULL conditions to accomplish the same thing.

    General Variables

    $QSTATURLOutput the web address of the QStat home page.
    $QSTATVERSIONOutput the version of QStat being run.
    $QSTATAUTHOROutput the name of the QStat programmer.
    $QSTATAUTHOREMAILOutput the email address of the QStat programmer.
    $HTMLEnable HTML friendly string output. Server results may include characters that have special meaning in HTML. These are replaced by equivalent SGML entities. QStat converts '<', '>', and '&' to '&lt;', '&gt;', and '&amp;'. Use this variable once in the header template.
    $CLEARNEWLINESConvert line feeds and carriage returns into spaces. Applies to all variables that output strings. Use this variable once in the header template.
    $RULENAMESPACESAllow spaces in rule names. Use this variable once in the header template.
    $IFConditional output. If the variable option is "true," the template is output up to a matching $ENDIF variable. If the variable option is "false," the template is ignored until after a matching $ENDIF. See Conditional Options for a list of supported conditional options.
    $IFNOTConditional output. Same as $IF, but the opposite sense.
    $ENDIFEnd conditional output. There must be one $ENDIF for each $IF and $IFNOT within a template.
    $NOWOutput the current local time.
    $TOTALSERVERSThe total number of servers to be queried.
    $TOTALUPThe number of servers up and running.
    $TOTALNOTUPThe number of servers either DOWN or TIMEOUT.
    $TOTALPLAYERSThe number of players found on all servers.
    $\Ignore the next newline. Not really a variable, but a way to curtail the output of extra newlines. Saves space in the output while the template remains readable. Must be the last thing on the line.
    $DEFAULTTYPEThe full name of the default server type specified with -default.

    Server Variables

    $HOSTNAMEOutput the host name of the server if known, otherwise the server address as given to QStat.
    $SERVERNAMEOutput the name of the server.
    $PINGThe time in milli-seconds to get a response from the server. If the server is DOWN or TIMEOUT, nothing is output.
    $PLAYERSThe number of players on the server.
    $MAXPLAYERSThe maximum number of players allowed on the server.
    $MAPThe name of the map being played.
    $GAMEThe name of the game being played. This is usually the name of the "mod" run by the server.
    $GAMETYPEThe type of game being played. Only applies to Quake 3. Typical values are Free For All, Capture the Flag, and Arena.
    $RETRIESThe number of retries needed to get the server status. This is a measure of packet loss.
    $IPADDRThe IP address of the server. Does not include the port number.
    $PORTThe port the server is running on.
    $ARGThe server address as given to QStat.
    $TYPEOutput one of the following depending on the server type:
        Quake
        Quake II
        Quake II Master
        QuakeWorld
        QuakeWorld Master
        Hexen II
        HexenWorld
        Unreal
        Half-Life
        Half-Life Master
        Sin
        Tribes
        Tribes Master
        Tribes 2
        Tribes 2 Master
        Shogo: Mobile Armor Division
        Quake III: Arena
        Quake III Master
        BFRIS
        Kingpin
        Heretic II
        Soldier of Fortune
        Gamespy Master
        Gamespy Protocol
    
    If the server type is not known, nothing is output.
    $TYPESTRINGThe server's type string (see GAME OPTIONS table.)
    $TYPEPREFIXThe server's type prefix (same as $TYPESTRING but in all-caps.)
    $RULE:nameThe value of a server rule. If the rule is not returned by the server, nothing is output. Must be used with the -R flag. Server rule names can include any alpha-numeric character plus '*', '_', '.', or ' ' (space). The use of space in a rule name will require use of the parenthesized format: $(RULE:name)
    $ALLRULESOutput all the server rules in the format name=value separated by commas. Must be used with the -R flag.
    $PLAYERTEMPLATEInvoke the player template. The player template is output once for each player on the server. Must be used with the -P flag.
    $RULETEMPLATEInvoke the rule template. The rule template is output once for each server rule.

    Player Variables

    The player template is only invoked if $PLAYERTEMPLATE is used in the server template.

    $PLAYERNAMEThe name of the player. If -htmlnames or $HTML is used, then HTML color font tags will be added for Quake 3 and Tribes 2 player names. If $HTML is used but -nohtmlnames is set, then player names will not be colorized.
    $HTMLPLAYERNAMEThe name of the player with HTML color font tags. Only Quake 3 and Tribes 2 are supported.
    $FRAGSThe number of frags scored.
    $DEATHSThe number of times player has died. This value is only available for Descent 3 servers.
    $PLAYERPINGThe player's ping time to the server. This value is not available from Half-Life servers.
    $CONNECTTIMEHow long the player has been playing. This value is only available from Quake, QuakeWorld, Hexen II, and Half-Life servers.
    $SKINThe name of the player's skin texture. This value is not available from ?? servers.
    $MESHThe name of the player's mesh (model). This value is only available from Unreal servers.
    $FACEThe name of the player's face texture. This value is only available from Unreal version 405+ servers.
    $SHIRTCOLORColor of the player's shirt. This value is only available from Quake, QuakeWorld, and Hexen II servers.
    $PANTSCOLORColor of the player's pants. This value is not available from Quake, QuakeWorld, and Hexen II servers.
    $PLAYERIPThe IP address of the player's computer. This value is only available from Quake and Hexen II servers.
    $TEAMNUMThe player's team number. This value is only available from Unreal, Tribes, and Tribes 2 servers.
    $TEAMNAMEThe player's team name. This value is only available from Tribes and Tribes 2 servers.
    $TRIBETAGThe player's tribe tag. This value is only available from Tribes 2 servers.
    $PACKETLOSSThe player's packet loss. This value is only available from Tribes servers.
    $COLORNUMBERSDisplay $SHIRTCOLOR and $PANTSCOLOR as numbers. Equivalent to -ncn command-line option. No output.
    $COLORNAMESDisplay $SHIRTCOLOR and $PANTSCOLOR using color names. Equivalent to -cn command-line option. No output.
    $COLORRGBDisplay $SHIRTCOLOR and $PANTSCOLOR using #rrggbb format. Equivalent to -hc command-line option. No output.
    $TIMESECONDSDisplay $CONNECTTIME as number of seconds. Equivalent to -ts command-line option. No output.
    $TIMECLOCKDisplay $CONNECTTIME in clock format (DhDDmDDs). Equivalent to -tc command-line option. No output.
    $TIMESTOPWATCHDisplay $CONNECTTIME in stop-watch format (DD:DD:DD). Equivalent to -tsw command-line option. No output.

    Rule Variables

    The rule template is only invoked if $RULETEMPLATE is used in the server template. The rule template supports equality tests on rule names and values. See RULENAME and RULEVALUE under Conditional Options.

    $RULENAMEThe server rule name.
    $RULEVALUEThe server rule value.

    Conditional Options

    These options maybe used with the $IF and $IFNOT variables. For example, to display player information, the following could be used in the server template:

        $(IF:PLAYERS)$(IF:FLAG(-P))
        The server has $(PLAYERS) players:
        $(PLAYERTEMPLATE)
        $(ENDIF)$(ENDIF)
    
    The template between the $IF and $ENDIF variables will only be displayed if the server has one or more players and the -P flag was given to QStat.

    GAMETrue if the server is running a "mod."
    PLAYERSTrue if the server has one or more players.
    QUAKETrue if the server is running Quake (the original).
    QUAKE2True if the server is running Quake II.
    Q2MASTERTrue if the server is a Quake II master.
    QUAKEWORLDTrue if the server is running QuakeWorld.
    QWMASTERTrue if the server is a QuakeWorld master.
    HEXEN2True if the server is running Hexen II.
    HEXENWORLDTrue if the server is running HexenWorld.
    UNREALTrue if the server is running Unreal.
    HALFLIFETrue if the server is running Half-Life.
    HLMASTERTrue if the server is a Half-Life master.
    SINTrue if the server is running Sin.
    TRIBESTrue if the server is running Tribes.
    TRIBESMASTERTrue if the server is a Tribes master.
    TRIBES2True if the server is running Tribes 2.
    TRIBES2MASTERTrue if the server is a Tribes 2 master.
    SHOGOTrue if the server is running Shogo.
    QUAKE3True if the server is running Quake III.
    Q3MASTERTrue if the server is a Quake III master.
    BFRISTrue if the server is running BFRIS.
    KINGPINTrue if the server is running Kingpin.
    HERETIC2True if the server is running Heretic II.
    SOLDIEROFFORTUNETrue if the server is running Soldier of Fortune.
    DESCENT3True if the server is running Descent 3.
    GAMESPYMASTERTrue if the server is a Gamespy Master.
    GAMESPYPROTOCOLTrue if the server is running a "Gamespy style" status protocol.
    RULE(name)True if the rule name is set on the server. Server rule names can include any alpha-numeric character plus '*', '_', or '.'. If $RULENAMESPACES is enabled, then rule names may contain a ' ' (space).
    FLAG(name)True if the flag name was used on the QStat command-line. The only flag names supported are: -H, -P, and -R. Any other flag name returns false.
    UPTrue if the server is up and running.
    DOWNTrue if the server is known to be not running. This is true if the server computer returns an ICMP indicating that nothing is running on the port. Only supported by some operating systems.
    TIMEOUTTrue if the server never responded to a status query.
    HOSTNOTFOUNDTrue if the host name lookup failed.
    ISEMPTYTrue if the server has no players.
    ISMASTERTrue if this is a master server.
    ISFULLTrue if the server has the maximum players.
    ISTEAMTrue if the player is a team. Only available with Tribes and Tribes 2 servers. Only applies to the player template.
    ISBOTTrue if the player is a bot. Only available with Tribes 2 servers. Only applies to the player template.
    ISALIASTrue if the player is using an alias. Only available with Tribes 2 servers. Only applies to the player template.
    TRIBETAGTrue if the player has a tribe tag. Only available with Tribes 2 servers. Only applies to the player template.
    RULENAMETrue if the rule name matches the variable argument. For example $(IF:RULENAME(version)) will be true when the rule template is outputing a "version" server rule. Only applies to the rule template.
    RULEVALUETrue if the rule value matches the variable argument. For example $(IF:RULEVALUE(1)) will be true when the rule template is outputing a server rule whose value is "1". Only applies to the rule template.

    APPENDIX B - QStat Configuration File

    QStat configuration files modify built-in game types or create new game types. New command-line options and template variables are created for new game types.

    Please refer to the default configuration file for examples. The default configuration file qstat.cfg can be found in the QStat package.

    Config File Load Order

    QStat will load one default configuration file and zero or more command-line configuration files. The default configuration file will be the first readable file found by the following search.
    1. File named in $QSTAT_CONFIG environment variable.
    2. Unix: $HOME/.qstatrc
      Windows: $HOME/qstat.cfg
    3. Unix: sysconfdir/qstat.cfg
      Windows: location-of-qstat.exe/qstat.cfg
    The default configuration file will be loaded before reading any command-line parameters. Configuration files specified on the command line will be merged with the contents of the default config file. In the case of duplicate game types, the command-line config files will be used. The QStat package includes a qstat.cfg that defines several new game types. If you want to use these game types, you need to place the file where it can be found by the default config file search. Or use the -cfg option.
    Unix Note: The sysconfdir is determined when qstat is compiled. For Unix compiles, the QStat makefiles default to /etc. To compile with a different sysconfdir, set SYSCONFDIR when compiling with gmake. For example, to set sysconfdir to /usr/local/etc
    % gmake SYSCONFDIR=/usr/local/etc
    Windows Note: The location-of-qstat.exe is the directory where the QStat executable (qstat.exe) is located. Just put the default qstat.cfg in the same directory as qstat.exe.

    General Syntax

    QStat configuration files describe game types using "stanzas". A stanza begins with a "gametype" line and is followed by several parameter lines ending with an "end" line. The general syntax looks like this:
    gametype type-string (modify | new extend type-string)
        parameter-name = parameter-value
        ...
    end
    
    The text in bold are keywords that must be used as shown.

    Parameter names are one or more words separated by spaces. The supported parameters and their meaning are listed in Gametype Parameters. Extra white space before, after and within a parameter name is ignored. An equal sign ('=') must separate the parameter name and the parameter value. There can be one parameter setting per line.

    Parameter values are one more characters or escape sequences. Leading and trailing spaces are ignored. All characters are used as-is except for backslash ('\') which begins an escape sequence.

    \\A single backslash ('\')
    \nA newline (ASCII char 10)
    \rA carriage return (ASCII char 13)
    \(space) A space (ASCII char 32). This escape should be entered as two characters: backslash followed by one space.
    \xHHA single character represented by the two-digit hexadecimal code. The hex digits H must be 0-9, A-F, or a-f.
    \DDDA single character represented by the three-digit octal code. The octal digits D must be 0-7.

    Defining New Game Types

    New game types are defined with the new keyword.
    gametype new-type-string new extend existing-type-string
        parameter-name = parameter-value
        ...
    end
    
    The new-type-string must not be a built-in type string. If a new gametype is defined multiple times in configuration files, only the last definition is used. The existing-type-string can be any built-in or configuration defined game type. However, QStat has the best support for extending Q3S, Q2S, GPS, UNS, and Q3M game types.

    The new game type has command-line option, type string and type prefix derived from new-type-string. The case of new-type-string is ignored. The command-line option and type string are always lower-case and the type prefix is always upper case.

    The new game type starts with the same parameters as the existing-type-string except for the type string itself. Game type parameters are set by the following parameter setting lines. Some parameters may only be used with master server and some only with game servers.

    We suggest that new-type-strings be as short as possible and end with an 's' for game servers and an 'm' for master servers. New game types should, but are not required to, set the name, default port, and template var parameters. The template var should be all upper-case and should not contain any spaces.

    Modifying Game Types

    Existing game types can be modified to update their query parameters.
    gametype existing-type-string modify
        parameter-name = parameter-value
        ...
    end
    
    The existing-type-string can be a built-in game type or a configuration defined game type.

    Only certain parameters can be modified: master protocol, master query, and master packet.

    Request Packets

    The request packets used for game server queries can be set with status packet, status2 packet, player packet, and rule packet. Request packets for master servers can be set with the master packet parameter.

    A request packet can only be set if the extended game type uses the same type of request packet. If a game type only uses the status packet, then an extending game type can only set the status packet.

    Request packet typically contain binary characters (those beyond the printable ASCII character set). These can be specified using the hex and octal character escapes.

    If the master packet parameter is set, the master protocol and master query parameters will be ignored.

    Game Type Parameters

    nameSets the name of the game type. Should be the full game name as used by the publisher.
    default portDefault network port used by the status protocol.
    status port offsetOffset of the status/query port from the game port.
    game ruleThe server rule containing the name of the game style or game mod.
    template varThe template variable used to test whether a server is of this game type.
    status packetThe status request packet. This is the first packet sent to a server of this game type.
    status2 packetThe second status request packet. If the server responded to the first status packet, then this packet is sent, but only if player or rule info is needed (command-line options -P or -R).
    player packetThe player request packet. Requests player information.
    rule packetThe rule request packet. Requests server rule information.
    master for gametypeSets the type of game returned by this master. The value must be a built-in or configuration defined game type.
    master protocolThe protocol number to use in the master request. The master server will respond with servers that match the protocol number. The numbers change with each version of the game that uses an incompatible network protocol. The master protocol is used mainly with Quake 3 based games.

    The master request packet will combine the master protocol and master query values.

    master queryThe query string to use in the master request. The master query string provides additional filtering for the master server.

    The default master request packet will combine the master protocol and master query values.

    master packetThe master request packet. Requests a server list from the master server. If master packet is set, master protocol and master query are ignored.