Readme.txt

6.24.2001

PunkBuster Server (beta) version 0.949

PunkBuster is (C) Copyright 2000-2001 by Tony Ray. All Rights Reserverd.
This readme.txt file must be distributed unaltered with all of the other files in the distribution archive as an unmodified whole.

The officially distributed win32 archive (zip) should contain the following files:
readme.txt
clreadme.txt
pb.exe
pb.ini
pbsvhl.dll
pbsvhl.cfg
cvar.cfg
sample.pbq
pbclhl.dll
pbclhl.dat
master.htm
cstags.htm
fatags.htm
hltags.htm
tfctags.htm
flftags.htm
dodtags.htm
wiztags.htm

The officially distributed linux archive (tar.gz) should contain the following files:
README
readme.txt
clreadme.txt
pb
pb.ini
pbsvhl.so
pbsvhl.cfg
cvar.cfg
sample.pbq
pbclhl.so
pbclhl.dll
pbclhl_
pbclhl.dat
master.htm
cstags.htm
fatags.htm
hltags.htm
tfctags.htm
flftags.htm
dodtags.htm
wiztags.htm

The version of the client executable pbclhl.dll distributed in this archive is (beta) version 0.964.

--------------------------------------

Up to date information on PunkBuster can be obtained from our website at http://www.punkbuster.com. Or, email us at staff@punkbuster.com. Thanks for using PunkBuster!

--------------------------------------

This readme is intended for people who are familiar with how to run and Administer a Half-Life server and/or one of the popular Half-Life mods supported by PunkBuster (such as TFC and/or CSTRIKE).

--------------------------------------

Contents:

I.	About the PunkBuster System
II.	Requirements
III.	How to set up a PunkBuster Server
IV.	Query Scripting
V.	Clan Tag Registry / Protection System
VI.	Screen Capture Facility
VII.	Logger Facility
VIII.	Troubleshooting
IX.	Future of PunkBuster
-A-	Addendum A: Changes since initial Release

--------------------------------------

I.	About the PunkBuster System

PunkBuster is a client/server software system that is designed to provide an online countermeasures system against cheating at multiplayer online games - specifically, games and mods based on the Half-Life engine by VALVe software.

Additionally, PunkBuster has a global Clan Tag Registry system built in to allow Clans to register their Clan Tags for protection on monitored servers. This prevents people from wearing their clan tag who aren't really in the clan. The list of registered tags is stored on our publicly accessible Internet website at http://www.punkbuster.com.

To parallel the way the Half-Life engine works, there is a PunkBuster Client to be run in the background of players' systems while they are running the Half-Life client. Also, there is a PunkBuster Server to be run to monitor the game servers. One PunkBuster Server can remotely monitor any number (in theory) of game servers remotely. The PunkBuster Server does not have to run in the background on the same machine as the Half-Life dedicated server engine.

The way the system works is roughly as follows:
- A PunkBuster Server is started
- A Half-Life game server (along with the rcon password for that server) is added to the list of monitored servers for that PunkBuster Server
- PunkBuster adds info to the Game Server's sv_contact field to "publish" the fact that the Game Server is being monitored; this info can be used by 3rd party Game Launchers (such as GameSpy to filter Game Servers with
- The PunkBuster Server regularly polls all game servers that it is monitoring
- The info obtained includes the list of players and their IP addresses
- The PunkBuster actively listens for connections from PunkBuster Clients over the network (Internet)
- If a connection cannot be established within a certain timeout period, then a timeout violation occurs (this will always occur when a player is not running the PunkBuster Client yet playing on a PunkBuster monitored game server)
- When a connection is established with a PunkBuster client, the Server initiates authentication (and possibly sending a small code patch to the client)
- The first step is a self-check to ensure that the PunkBuster system is running as designed on the player's system with no proxy or hack-around software acting like a valid PunkBuster client
- Then a series of codes are passed back and forth between the Client and the Server so that PunkBuster can determine if the player has known cheats on his or her system
- One of two things will then occur: If no cheats/hacks are found, then the Player is authenticated; otherwise, a violation is raised and a message is broadcast to all players in that particular game
- If that server is set for Optional Compliance, then the Player is allowed to continue playing on that server only having had the message about the violation sent to all players
- If that server is set for Required Compliance, then the Player is removed from the server (each admin has flexible options for either Banning the player or merely Kicking)
- After a number of minutes, each player is reauthenticated from scratch to avoid the possibility of players cheating only after authentication
- Also, players who are wearing a Clan Tag that has been registered will either be validated with the proper password and auth key or will be asked to remove the tag

Every few minutes, each PunkBuster server will connect as an http client to a hard-coded website on the Internet to download the current list of Registered Clan Tags and list of Master PunkBuster Servers.

Also, each PunkBuster Server will routinely attach to a Master PunkBuster Server to check for updates and also to upload the list of game servers being monitored. In this way, the PunkBuster Master Servers will always have a current list of all PunkBuster Servers running and the Game Servers they are monitoring.

--------------------------------------

II.	Requirements

There are 2 versions of PunkBuster, one for Win32 platforms and one for Linux. Both versions can remotely monitor games running on either or both platform simulatneously.

There are no specific memory or bandwidth requirements. The system has been designed to use VERY few system resources. Our tests indicate that the average PunkBuster Server should run for days without consuming more than a few minutes of cpu time. Also, bandwidth is throttled and even a very busy server should not exceed a few KBytes per second bandwidth at peak usage. Unlike the game engine, a powerful system with high available bandwidth is not required to run PunkBuster.

--------------------------------------

III.	How to set up a PunkBuster Server

There is no setup or installation procedure. All the files that were unzipped along with this readme.txt file should just be placed in any directory on your system. You can create a new directory to hold the PunkBuster Server system, or you can run it from within an existing directory - it doesn't matter.

Win32:
When you wish to start the PunkBuster Server, simply execute the PB.EXE file (most people will create a shortcut to this executable although it isn't required). The PunkBuster window will appear shortly on your screen. There is a command line interface whereby you can type commands and the commands plus any related output will be displayed in the main part of the program window.

Linux:
When you wish to start the PunkBuster Server, simply execute the pb file through a shell command (./pb or equivalent). The entire server is run from the command line interface.

QUICK-START: To get PunkBuster monitoring up and running quickly, simply type in the following line into the PB Server console after it is launched (be sure to substitute your appropriate info):

Optional <Game_Server_IP>:<Game_Server_Port> -1 <rcon_password>
For Example:
Optional 1.2.3.4:27015 -1 rpass

The above line will start a monitoring session with your Game Server in Optional Compliance mode. That means that PunkBuster will not kick players found in violation or who are not running the PunkBuster Client Software. If you want Required mode, then just use the same line except with the word Required in place of the word Optional shown above.

Starting with version 0.949, PunkBuster can be configured to use a specific TCP port rather than using the historical hard-coded port 24347. This means that you can now run multiple instances of the PunkBuster Server on the same machine concurrently. To specify a listen port, add +PORT<#> to your startup command line. For example, in win32, use "PB.EXE +PORT33333" to have your PunkBuster Server listen to port 33333; in linux, similarly use "./pb +port33333". Note that there is no space between the "+PORT" and the number. If you just use "+PORT" by itself, PunkBuster will choose a random port between 10,000 and 25,000. The command "Ports" typed into the console will display which listen ports your PunkBuster server is currently using.

Customizing and configuring your PunkBuster Server is best done using config files. Config files used by PunkBuster are simple text files with a .cfg extension containing statements, commands, and variable settings. The standard default config file that is loaded when the PunkBuster server starts is called pbsvhl.cfg. A sample pbsvhl.cfg file is provided in this archive. You can specify that the PunkBuster Server load a different config file on startup by using the +LOAD <filename> command line parameter (or put it in your shortcut target). You can also create other config files (you must use the .cfg extension) and load them any time with the Load <filename> statement. You can even place Load <filename> statements inside config files (they can be nested to 3 levels if desired). The pbsvhl.cfg file contains commands that are accepted by the PunkBuster engine just as if they had been typed in the command line interface.

PunkBuster Servers can be administered remotely with a common telnet client using port 24349. In order to establish Remote (Telnet) Access (which is denied by default), you need to set the MaxRemote variable to at least 1 in your pbsvhl.cfg file and also add at least one password to your list using the password statement (described in the sample pbsvhl.cfg file). To disconnect from a Remote Session with PunkBuster, type in logout (or logoff) - do not type quit or exit as those commands will be passed to the PunkBuster Server and the PB Server itself will exit if you have level 1 access. See the sample cfg files that came with this readme for more information. **NOTE about security - the "Telnet" access provided by PunkBuster does not give any remote machine access to the computer running PunkBuster. Only regular PB commands are accepted and acted upon. No access to the operating system, shell, or outside commands / file utilities is provided.

Starting with version 0.949, you may also specify a different TCP listen port for remote administrative connections. Use the "+RPORT<#>" command line option for this feature. For example, to listen on port 9500 for remote sessions, use "PB.EXE +RPORT9500". Note there is no space between "+RPORT" and the port number. If you use "+RPORT" by itself, then PunkBuster will choose a random port between 10,000 and 25,000. The command "Ports" typed into the console will display which listen ports your PunkBuster server is currently using.

Typing a variable name with no parameters will display the current value associated with that variable. The PunkBuster server will routinely update local database files from the World Wide Web automatically. The Update button or command can be used to manually initiate an Update. The Scroll Lock button (win32 only) can be used to pause output to the main window so that you can go back and review logged information (and copy to clipboard, etc.). Pausing via Scroll Lock does not affect the server, only the output to the main window. You should "unlock" the scrolling as soon as you can as information can be lost if it is locked for too long.

LOGGING: The PunkBuster Server will log to both the Screen and to Files in various levels that can be set with commands (see the pbsvhl.cfg sample file for more info). All file logging will be done to files in the pblogs subdirectory (folder) which will be created the first time the PunkBuster Server is started. Two special log files called violator.log and cheater.log contain all Player violations. The other log files are based on the date the log file was started (i.e. YMMDDXXX.LOG) where the XXX represents a sequential number from 001-999. When a log file fills up, PunkBuster simply closes it and starts a new log file with the next available sequential number. It is up to the admin to purge the LOGS by simply deleting old unwanted files based on the filename.

There are 3 simple commands that you can use to get information about your running PunkBuster server. The SLIST command will list the servers being monitored. The PLIST command will list the players who are (or were) playing on the monitored servers. The RLIST command will list all Remotely connected users. We intend to expand the use of these simple listing reports in future releases of the PunkBuster server.

--------------------------------------

IV.	Query Scripting

This powerful new feature is being developed primarily to benefit participants in Organized Matches that are being monitored by PunkBuster. In short, PunkBuster Query Scripting provides for PunkBuster to query and monitor server side variables to ensure that they match pre-arranged settings throughout the course of a match. Variables are queried based on pre-written scripts and each query result is written to the PunkBuster log, the console screen, and all connected remote "telnet" users. Any discrepancies from expected values are additionally explicitly announced into the running game via an rcon say message so that all players are aware of the discrepancy as soon as it is discovered. Leagues and tournaments that have standard config files written for match play can now have Game servers automatically queried throughout the course of matches to ensure that the settings perfectly match the standard. Used in conjunction with "telnet" access level 4, visiting teams can have their representative(s) fully log all Query Results and furthermore manually enter any server-side variables during the match (except rcon and admin related variables) to have them manually queried at any time before, during or after the match. For security, "telnet" access level 4 does not allow any PB settings to be changed. It is provided strictly for logging and generating manual Query Requests. Also, manual Query Requests are only honored if Query Scripting is currently running for the monitored Game Server.

PunkBuster Query Scripts must use the .pbq file extention and contain text only. Query Scripts can be created using any text editor or can be generated by modifying our provided sample.pbq. A .pbq file simply contains a list of server variables (one on each line) with up to 2 additional parameters per variable to tell the PB Server how to query and optionally monitor each variable. Additionally, there is one command, called DisplayScript that can be issued only inside .pbq scripts. This setting instructs PunkBuster how often to output (display) the full list of server variables and parameters associated with the currently running script. The default setting is 30 minutes, but can be set to any value between 0 and 120. Setting DisplayScript to 0 tells PunkBuster to NOT output the Script variables at all. For example, the line:

DisplayScript 15

instructs PunkBuster to list to the PB screen, log and "telnet" clients all of the variables in the currently running Query Script every 15 minutes. As PunkBuster monitors the various variables during the course of the match, each Query Request, Response and Discrepancy are also output. The format for specifying variables to query is as follows:

<variable_name> <cycle_period_in_seconds> [<optional_expected_value>]

So, for example the line:

mp_teamplay 300 11

would instruct PunkBuster to query the Game Server once every 300 seconds (5 minutes) at some random point during each consecutive 300 second period and compare the result to the given expected value of 11. The actual Query Send and the Query Response are output for all attached users. If a Query Response comes back with a value other than 11, then all participants in the game will see an "rcon say" message warning of the discrepancy. For another example, the line:

mp_timeleft 120

would instruct PunkBuster to query for the time remaining every 120 seconds (2 minutes) at some random point during each consecutive 120 second period. Since the value is expected to change, no monitoring of the variable is possible so its value is output to attached users only as part of the Query Result.

Three new commands have been added to the PunkBuster system to allow for the starting and stopping of Query Scripting and also for manual entry of variables to be queried in addition to the variables specified in the script. You must be familiar with how PunkBuster keeps track of Game Servers in order to effectively use these new commands. When Game Servers are added to the internal PunkBuster list, they are each given an ID. The first Game Server is ID=1, the second is ID=2, etc. The slist command will also display a list of monitored Game Servers showing their IDs in the first column.

To start a Query Scripting session for a specific Game Server, use this command:

QueryStart <game_server_id> <filename>

for example, the command:

QueryStart 1 sample

Would begin the process of monitoring the first monitored Game Server using the variables and settings stored in the sample.pbq file file (PunkBuster will add the .pbq extension if it is left off). Similarly, to stop the process, use something like:

QueryStop 1

to end the variable-monitoring session for the first Game Server. Only one Query Script can be running for each Game Server at any given point in time. When monitoring multiple Game Servers with the Query Scripting feature, each is monitored independently from the others. Game Server ID=2 can be using the same or a different .pbq file from the one being run by Game Server ID=1.

If a Game Server is currently running a Query Script, then the QueryVar command can be used from the PunkBuster program screen or by any attached remote "telnet" user to immediately query the value of a server variable. The format of the QueryVar command is as follows:

QueryVar <game_server_id> <variable_name>

For example, entering:

QueryVar 1 sv_unlag

will cause the Query Scripting engine to immediately send a Query Request to Game Server ID=1 asking for the current value of the sv_unlag variable. The Query Result will be output when it is received from the Game Server. All Query Sends, Results and Discrepancies (whether originating from inside a .pbq script or from a manual QueryVar command) show the Game Server IP Address and Port number as part of the logging.

NOTE: It is possible to run an "empty" Query Script with no variables if you only wish to have the ability to generate manual QueryVar commands with no automated variable-monitoring.

--------------------------------------

V.	Clan Tag Registry / Protection System

PunkBuster offers the Clan Tag Registry / Protection System in an effort to allow Clans to register their clan tags with a password so that only their members will be allowed to wear the registered tag on PunkBuster monitored servers. This is designed to prevent non-members from acting like they belong to a clan or from impersonating members.

When a PunkBuster Server starts up, it will search for a specific place on the World Wide Web to download the current database of PunkBuster registered clan tags. This database is used to validate players who wear registered tags during gameplay on monitored servers by checking the password and auth keys that the players have entered into their local PunkBuster Client software. If your PB Server is LAN based or otherwise cannot reach the Internet WWW server where the tag database is stored, you can manually download tags.zip from the Download page on our website at http://www.punkbuster.com and extract the database (.htm) files into your PB Server directory in order to update your system. The PB Server will read these files upon startup before trying to update them from the World Wide Web.

With PB Server version 0.937, a new set of functions was added to allow PB Admins some flexibility in dealing with special situations regarding Tags on their monitored Game Servers. The ExtraTag statement has the following format:

ExtraTag <password> <tag>

Using this statement adds a record to the list of Extra Tags in your PB Server. This list can hold up to 10 Extra Tags at any given time. If the <password> parameter is specified as "", then that indicates that anyone can wear the tag specified by the <tag> parameter in the ExtraTag statement. If an actual password is specified, then players will need to have entered the correct password into their local PB Client profile if they wish to wear that tag on your server. The auth key field in the PB Client is ignored for Extra Tags. Also, Extra Tags are case-insensitive as opposed to regular Registered Tags and Extra Tags are in effect whether worn as a Prefix or as a Suffix.

The ClearTags statement empties the current list of ExtraTags. The TList statement displays the current list of Extra Tags on your PB Server console screen.

These functions have a couple of useful applications. For example, if you wish to require a password for players who want to wear certain tags such as [ADMIN] or [CL] (clan leader), or [DCL] (deputy clan leader), then you can use a line such as:

ExtraTag pword [ADMIN]

If you wish to have the tag [XYZ] ignored by PunkBuster's validation system, then use the line:

ExtraTag "" [XYZ]

Used in conjunction with the Load statement, you may want to set up several config files for different scenarios. For example, you could create a config file called normal.cfg that contains:

ClearTags
ExtraTag test [ADMIN]

and then you may have another config called match.cfg that contains:

ClearTags
ExtraTag pw [CL]
ExtraTag pw2 [DCL]
ExtraTag "" [ABC]
ExtraTag "" [XYZ]

then you could put "load normal" into your pbsvhl.cfg to get executed upon server startup and manually type "load match" whenever you wanted the second set of tags to be in effect. At some later point, you could type "load normal" to restore your Extra Tag list to the first set of tags shown above.

Starting with PunkBuster Server version 0.949, the TagPenatlies setting is available to disable the penalty associated with a non-validated clan tag on specific PunkBuster Servers. The default for this setting is 1 which means that if a monitoring session is running in Required mode, players will be kicked for failing to remove a non-validated clan tag. You can disable the default behavior with the following line:

TagPenalties 0

Either by typing directly into the console or by placing it into your pbsvhl.cfg configuration file. When this setting is 0, then even when PunkBuster is running in Required mode, players will not be kicked for failing to remove a non-validated tag. This does not disable tag checking and will force messages to be broadcast in-game when a player fails a tag check. The purpose is to alert players to servers where tag-related penalties have been disabled.

--------------------------------------

VI.	Screen Capture Facility

New with version 0.949 of the PunkBuster server is the ability for PunkBuster Admins to request and retrieve player-side screenshots during gameplay within the PunkBuster system. Currently, the only way to view screenshots captured by PunkBuster is by running the win32 version of the PunkBuster server on a system set to 16bit color depth. However, All PunkBuster servers can request and retrieve images. During the intitial broad testing of this feature, image sizes will be limited. Also, bandwidth is throttled at 1K/sec so as not to adversely affect players on slower connections.

Players will not know that a screenshot has been taken until after it is fully delivered to the PB Admin. At that point a message will be sent to the PB Client (which is usually echoed to the game console unless the player has disabled console echo) saying that a screenshot has been delivered. Also, a log is kept by PunkBuster clients of all screenshots that have been sent to PunkBuster servers. This log file is called pbss.log and is stored in the PunkBuster Client folder. This log is kept as a protection for clients against people who would try to fake images as if they were taken by PunkBuster when they really were not. The log contains several pieces of important information that can be used to determine if a PunkBuster capture files are legitimate should the need arise.

NOTE: If you request a screenshot from a player who has switched to an application (or their desktop) so that the game is not the application with focus, then the PunkBuster Client on their end will refuse to take the screenshot and you will see a message that says "Capture Denied ...". In this case, you can retry the capture attempt as often as you like and it is up to you to decide at what point you wish to deal with the player (kick/ban, etc.).

To request and retrieve a screenshot from a player, the PB Admin has 2 available commands: "SS <player id #> and "SSN <name>". You can use the plist command to list players being monitored by PunkBuster and use the first column (player id) with the SS command to request a screenshot from a specific player. For example, "SS 3" will request a screenshot from player #3. You can also use SSN to request a screenshot from a player or players using a specific name or substring. For example, "SSN Goofus" will request a screenshot from all players who have the text "Goofus" in their current playing name (this is not case sensitive so "Goofus" is the same as "GOOFUS" and "goofus"). You will be informed of how many screenshots were requested with each command. The PunkBuster server will not accept screenshot requests for a given player more frequently than once every 3 minutes unless you receive a "Capture Denied" message for that player. In that case, you may re-request at will.

Depending on the size of the image (see below for more information about customizing image sizes and properties), it may take anywhere from 2 seconds to about 90 seconds for an image to be fully retrieved. Images are transferred at the maximum average rate of 1K per second so as to affect low bandwidth connections as little as possible. The default image size is 300 x 125 pixels and is taken from the center of the player's screen. Default images usually require approximately 65-75 seconds for retrieval. PunkBuster image files are saved by the PunkBuster Server in the subdirectory called pbcaps inside the directory where the PunkBuster Server runs from. Image files have a filename that equals the WONID of the player and have a ".pbc" file extension. When a captured image is written to the pbcaps directory, a corresponding HMTL file (with .htm extension) is also written as a separate textual log of the image file. Multiple image files from the same player will overwrite one another so that the last one captured will be kept. If you wish to keep image files, you must rename them or copy them to a different directory after they have been saved. After the testing phase, support will be added for keeping a number of previous images for each player.

Once an image is fully retrieved, the PunkBuster Server will issue a message to the console screen to notify you that the capture is finished and will also give a status indicator of whether there was an MD5 match or not. An MD5 match indicates that the capture was successful with zero errors in transmission of the image. The MD5 (among other things) is stored in the player's client side log so if the captured image is alterred, the MD5 signature will no longer match the one output in log on both sides of the transaction.

Immediately after writing each image file, PunkBuster calls a system batch/script file called pbcaps.bat stored in the pbcaps directory with the images. This file is not supplied and if it doesn't exist then nothing happens at all. This feature is provided for Admins who want to customize what happens to image files. The batch/script is called with the filename (minus extension) of the image file. For example, if the image file written was named "12345.pbc", then the batch file will be called as ".\pbcaps\pbcaps.bat 12345" (in Linux, forward slashes are used). It is left as an exercise for admins to use this feature as they see fit. Linux admins may want to copy the image files to a win32 machine on their network using Samba or perhaps ftp them to a win32 so that the images can be viewed. Other admins may want to write a script to archive the images.

To View a PunkBuster image file from the win32 version of the PunkBuster Server, simply type "View <filename>" into the PunkBuster Server console. For example, to view the image for player having wonid of 12345, type "pbcaps\12345.pbc". Currently, DirectX and also 16bit color depth is required to use the view feature. As the image is displayed in the upper left corner of the desktop, text related to the image is output into the PunkBuster Server console. This text shows the name the player was wearing, the game server's IP:Port, the player's IP:Port, the player's WONID, and the slot # on the game server that the player occupied when the screenshot was taken.

There are several settings that can be used to customize the PunkBuster Screen Capture Facility. You can type SSInfo from the PB Console to see the current values for these settings. The SSView setting defaults to 0. When set to 1 with "SSView 1", this command automatically displays each captured screenshot immediately after it is fully retrieved. You can always manually view an image with the "View" command described above. The SSWidth and SSHeight settings allow you to specify the requested area size on the player's screen that you wish to capture. They default to 300 and 125 respectively. If you request a width or height that is greater than the actual width or height of the player's screen resolution, then your request will be modified appropriately. The SSX and SSY settings allow you to specify the position of the center of where the screenshot will be taken as a percentage of screen width and height. They both default to 50 percent which indicates the center of the screen. Specifying 0, 0 for these would indicate the upper left corner and 100, 100 would indicate the lower right corner of the screen. Specifying -1 for either or both will cause a random percentage between 0 and 100 to be used. The SSRate setting allows you to specify the (pixel) sample rate of the screenshot. This setting defaults to 1 but can also be set to 2 or 4 (setting to 3 causes 1, 2 or 4 to be used randomly). This setting allows you to capture a greater area of the screen by skipping pixels. Sample Rate 2 tells PunkBuster to only capture every 2nd pixel in both directions reducing image size by 4. Sample Rate 4 tells PunkBuster to only capture every 4th pixel in both directions reducing image size by 16. The higher the sample rate, the less sharp the image will be. In most cases, all three sample rates provide a very nice screenshot.

During the testing phases for this facility, image sizes will be limited to 40,000 pixels per image. If your specified parameters would cause an image size of greater than 40,000 pixels, then PunkBuster will reduce the specified width and height appropriately.

KNOWN ISSUES with the Screen Capture Facility:
-Some systems obfuscate the video card's memory buffers and PunkBuster is not able to always capture the actual image displayed on the screen each time. We are working to resolve this. In our estimation from testing, this affects a very small number of players. In any case, the image captured is a game image, it just may not represent the image displayed to the player at the moment the capture occurs. It is a timing issue.
-The PunkBuster Client will not capture at all for players running in Software Mode (as opposed to OpenGL/Direct3d) unless they are also playing in Windowed mode (hl.exe -window). We may or may not add support for these types of captures in a future version. If you request a capture from a player running in Full Screen Software Mode, the message that comes back to the PB Server Console says "Capture Denied ...". This is the same message you get if the user has Alt-Tabbed into a different application. It is up to you to decide if you want to kick/ban the player or let them continue playing without you being able to get their screenshots.
-For best results, we recommend requesting screenshots from players who have already been authenticated by PunkBuster whenever possible.

--------------------------------------

VII.	Logger Facility

New with version 0.949 of the PunkBuster server is the ability to send PunkBuster logging to a remote IP address which is listening at a specific port for logging. This is mainly useful for leagues and organized events which may wish to collect PunkBuster logs of all matches and store them in a central place.

To run a PunkBuster Logger (for collecting logs from regular PunkBuster servers), use the +LOGGER command line option. In win32, for example, use "PB.EXE +LOGGER8000" to start listening on port 8000. Note that there is no space between "+LOGGER" and the port number. Just starting PunkBuster in Logger mode does not automatically start the logging process. There are 2 commands use to control logging when a PunkBuster Server is in Logger mode. The command "LogStart <directory>" is used to initiate a logging session. When this command is issued, PunkBuster will create the specified directory if it doesn't already exist and begin writing log files into this directory as logging comes in from various regular PunkBuster servers that are configured to send to the Logger's specific IP address and Port. To end a logging session, type LogStop. Each log is in a separate file and the filename is based on the IP address and random incoming port number allocated when the connection was initiated. For the filenames, periods in an IP address are converted to dashes.

To configure a regular PunkBuster Server to send logging to a PunkBuster Logger, use the command "LogTo <IP:Port>" either from the command line or from inside your pbsvhl.cfg (or other) config file. For example, the command "LogTo 1.2.3.4:5555" will cause your PunkBuster server to start sending all loggable output to a waiting PunkBuster Logger at IP 1.2.3.4 listening at port 5555. If there is no Logger found at that IP:Port combination, then your PunkBuster Server will continually re-try to establish a connection there every 5 minutes or thereabouts. To discontinue sending log output, simply type "LogTo" by itself.

--------------------------------------

VIII.	Troubleshooting

- Firewall problems: The PunkBuster server uses port 24347 for TCP traffic. If you use PunkBuster behind a Firewall, Proxy or NAT device, etc., you'll need to pass TCP traffic bound to port 24347 directly to the machine that is running the PunkBuster server. The PunkBuster client uses tcp port 24348 in a similar way. The PunkBuster server also uses TCP port 24349 for Telnet (remote) access if that feature is enabled by your PunkBuster configuration (disabled by default).

- Linux Segmentation Fault. A few admins have resolved this simply by setting up DNS on their Linux machine and simplifying their etc/hosts file. A future version of PB Server will be released to work without requiring DNS.

- Linux "Cannot Create Detached Thread" messages. This means that your Linux Distribution does not support LinuxThreads (also known as POSIX Threads or pthreads) to the degree necessary for PunkBuster to operate properly. Usually, newer Linux installations will not have this problem.

- If your Linux PB Server is prone to "freeze" after running for a long period and then uses the remaining cpu cycles, try using the Linux renice command to lower the priority of the PB Server after it is launched. You can use the ps command to obtain the pid(s) of the PB Server, then type in "renice +15 -p <pid>" to lower the priority (15 is a suggested value that could range from 1 to 20). This will keep PB from interfering with other running processes if it misbehaves. Thanks to users Tom Livingston and Aleksander Adamowski for providing help with this suggestion.

- PunkBuster runs but never "sees" any players from some or all servers being monitored: You're most likely running an old version of the server, for best results you need to be running build 1490 or higher of the Half-Life engine.

- PunkBuster starts but then immediately exits: Examine the pb.err and/or pbsvhl.err files for information about what problem(s) were encountered.

- If you experience lag spikes (whether or not related to PunkBuster) running your Half-Life server under windows, uncheck (clear) the Quick Edit Mode and Insert Mode check boxes on the Options tab of the window properties where your Half-Life console runs. Some Admins also report that changing the HLDS window font to a true type font will reduce or eliminate these type of lag spikes.

- A user reported notable lag when running PunkBuster with certain virus scanning software. Try temporarily disabling your virus scanner if you experience unusual sluggishness and if that solves the problem, then let us know what virus scanner you use so we can hopefully address the conflict.

- Any bug reports or other problems should be directed to support@punkbuster.com - thanks

--------------------------------------

IX.	Future of PunkBuster

Many features are planned for both the PunkBuster Client and Server pending results of the beta test. Right now, we want to focus on getting the system to run smoothly across the board. We intend to add detection for all known cheats being used during gameplay on Half-Life based systems.

At some point, we hope to expand to other game platforms such as Quake, Unreal, etc. Once we prove that the overall system works and the community improves as a result, finding a way to fund expansion should be fairly easy (we hope).

--------------------------------------

Addendum A

new changes for beta version 0.949 (6.24.2001)
-	added the +LOGGER<#> command line option (see chapter 7 in this readme for info on the Logger Facility)
-	added LogStart and LogStop commands for the Logger Facility
-	added LogTo command used to send logging to a PunkBuster Logger
-	added +PORT<#> and +RPORT<#> command line options (see chapter 3 in this readme for more info)
-	added Ports command to list the listen ports currently in use by the PunkBuster server instance
-	PunkBuster no longer uses a temporary file (.tmp) to inhibit multiple instances
-	added TagPenalties (defaults to 1) to allow disabling of kicking for non-validated clan tags
-	added support for the Query Script Request hotkey which is available in PB Client 0.963
-	added the Screen Capture Facility (see chapter 6 in this readme)
-	NOTE: Screen Capture file format has changed from the test version 0.948

new changes for beta version 0.948 (5.30.2001)
-	increased the maximum LogThreshold value to 1,000,000
-	initial test feature for screen captures

new changes for beta version 0.947 (5.12.2001)
-	fix new bug with plist not removing old items
-	now PB server sends details of CVar violations to the associated PB Client

new changes for beta version 0.946 (5.8.2001)
-	correct a couple of minor bugs with new cvar checking feature

new changes for beta version 0.945 (5.8.2001)
-	removed the 111 Master Socket error messages from the Linux version
-	fixed the problem loading cstags.htm
-	PB Server now sends its version number to clients at the end of the MOTD
-	now checks the sv_contact field every 5 minutes
-	saves the original sv_contact field and resets it when monitoring stops
-	new max for the MaxPending field of 210 seconds
-	added a whole new feature to check player client-side cvar settings - see the new cvar.cfg file for info

new changes for beta version 0.944 (5.3.2001)
-	addressed the bug that showed old players in the plist
-	fixed sayfilter bug related to authentications
-	in violation broadcasts, the player's WONID is now listed in parentheses after the name
-	fixed bug that caused status requests to be ignored sometimes
-	PB Server now no longer sends lists of authed and non-authed players at certain intervals
-	AuthPulse and ViolPulse are now obsolete
-	Greatly reduced the number of messages sent directly to Players' consoles
-	the MaxPending variable now defaults to 60 seconds and can be set from 50 to 120
-	fixed the bug that was causing Violation #15 and #18 for some users
-	the PB Server will now continue trying to bind to the listen port indefinitely until it works
-	fixed the bogus http 302 error message that some admins were seeing when downloading tag data
-	added new capability to kick players with Bad Names using 2 new commands BadName and BadFullName
-	sample line added to pbsvhl.cfg file in this archive to kick players using the invisible name hack
-	removed the meaningless Master Socket Read error messages
-	added code in the win32 version to self-focus after an auto-update

new changes for beta version 0.943 (4.7.2001)
-	fixed bug that was causing players to not drop off the Player List after a period of inactivity

new changes for beta version 0.942 (4.4.2001)
-	closes PB connections if players have been gone from a monitored game for about 4 minutes without returning
-	now waits until a player name is parsed from the game before starting the authentication process
-	the AuthType setting is no obsolete
-	the Client initiated 'Status' function works better

new changes for beta version 0.941 (4.2.2001)
-	added ability to connect to Master PB Servers on a different port if there is net congestion
-	added trial support for bots (Wonid=0 and IP:Port=0:0) getting technical authentications
-	Linux version now shows pid in starting log line

new changes for beta version 0.940 (3.27.2001)
-	the PB Server no longer attempts to initiate connections with PB Clients
-	the MaxInits, InitPulse, and InitConnect settings are no longer meaningful
-	a new setting called GracePeriod has been added to determine the timeout period in seconds (default 60) for Client-initiated connection attempts; if a Player is found on a monitored Game Server and that Player's PB Client doesn't connect to the PB Server during the GracePeriod, then a Timeout violation will be raised
-	the RepeatPenalty setting can now be set to 0 so that, if desired, it is now possible to configure your PB Server to run in Required Mode but never ban players (use BanLen 0 and RepeatPenalty 0 for this effect)

new changes for beta version 0.939 (3.16.2001)
-	support added for an upcoming PB Client release with full auto-connectivity

new changes for beta version 0.938 (3.13.2001)
-	updated to work with the new rcon challenge scheme in the HLDS servers
-	added new command called defaults that resets all PB variables and settings to their default values
-	added support for new BanType 3 which bans by both WONID and IP Address at same time; BanType 1 bans by IP address, BanType 2 bans by WONID, and BanType 3 bans by both (BanType 2 - WONID is the default)

new changes for beta version 0.937 (2.22.2001)
-	validates tags for 3 new mods: FLF, DOD, and WIZWARS
-	added ability to optionally use colon between IP and Port (in place of the space) on server and server+ statements
-	added 2 new statements Required and Optional that use the same format as server+; for example, "required 1.2.3.4:27015 -1 pw" now adds monitoring of a game server at 1.2.3.4:27015 in Required mode with default sayfilter (-1); these can be used to update existing monitors as well; the Penalties statement is now no longer needed to set up monitoring in either Required or Optional mode
-	added new statement "sfile <fn>" that exports all currently monitored servers to a cfg file using appropriate PB config format
-	added 2 statements "GoReq <id>" and "GoOpt <id>" that let you change the compliance mode of a specific monitoring session; use the slist command to retrieve the server ids for currently monitored games; if <id> is 0 or not specified, then all currently monitored games will be set to the specified compliance mode; for example, just using "GoReq" by itself will put all monitored games immediately into Required mode and using "GoReq 1" only puts monitored game #1 into Required mode
-	added support for up to 10 Extra (custom) Tag designations (see section V above)
-	added tlist statement to list the Extra Tags in your system
-	**NOTICE** at this time the following commands are considered obsolete and will only be supported short term: sread (replaced by load), swrite (replaced by sfile), penalties, server and server+ (all 3 replaced by new Required and Optional statements)

new changes for beta version 0.936 (2.12.2001)
-	rewrote Linux threading code to only use Detached pthreads (POSIX Threads) which are automatically "cleaned up" by the Linux O/S upon Thread termination
-	added the new Password, RemPassword, and CloseRemote commands; see the sample pbsvhl.cfg for more information
-	added the new rlist command which displays all currently attached remote connections (telnet users)
-	added the new load statement which allows Admins to load different PB config files; nesting is provided up to 3 levels deep; see the sample pbsvhl.cfg file for more information
-	added the new +LOAD <filename> command line parameter to specify that PB load a replacement PB Config file rather than the default pbsvhl.cfg; note that <filename> will have .cfg appended if it is left off

new changes for beta version 0.935 (2.9.2001)
-	rewrote Signal Trapping for Linux version
-	rewrote the code that handled Accepting Connections from Clients

new changes for beta version 0.934 (2.9.2001)
-	fixed glitch in Linux version that was causing alot of bogus #15 violations

new changes for beta version 0.933 (2.9.2001)
-	rewrote Signal Trapping for Linux version
-	changed Linux socket binding to address the "Unable to Bind" errors on restarting
-	removed the obsolete PBURL setting and stopped appending the PB Server Address to Broadcast messages (BCMsg2)

new changes for beta version 0.932 (2.7.2001)
-	PB Servers now update the sv_contact field on monitored Game Servers with two sets of information both enclosed in curly brackets; {PB REQ} means the Game is monitored for Required Compliance and {PB OPT} means Optional; the 2nd set of brackets will enclose the address of the PB Server itself, for example {11.22.33.44} - if the PB Admin sets the PBURL variable, then its value will be shown in the 2nd set of brackets; most Game Launchers can filter using the sv_contact field so you can filter by all PB games by looking for "{PB" and for Required only by looking for "{PB REQ}"
-	new setting called InitConnect which defaults to 1 (yes); if InitConnect is set to 0, then the PB Server will not try to initiate connections with Clients, but will only accept incoming connection requests

new changes for beta version 0.931 (2.4.2001)
-	rewrote tag validation procedure to better handle duplicate tags
-	fixed glitch with command line parsing that caused PunkBuster to act on some folder names
-	addressed zombie glitch with Linux flavor of the PB Server
-	fixed RH7 Linux crashing bug
-	fixed Linux seg fault problem that was occuring at the very end of execution
-	fixed parsing glitch in the server+ statement

new changes for beta version 0.930 (2.2.2001)
-	fixed glitch in Master PB server that prevented many users from reliably getting a successful connection to it
-	fixed the looping client update for Linux PB Servers
-	fixed the 'no game say' glitch
-	fixed the auto update code for servers so that future versions should auto-update properly from the PB Master server
-	there is now no reason for us to only release even numbered versions via the master server so that practice will be discontinued

new changes for beta version 0.929 (2.1.2001)
-	completely rewrote the way PunkBuster is launched; there is now a pb.exe executable that reads a pb.ini file and connects to the specified dll file (default is DLL=pbsvhl.dll); this has many benefits one of which is to fix the auto update procedure
-	new tag validation code to address problems older PB versions have had validating some tags

new changes for beta version 0.927 (1.23.2001)
-	PunkBuster Servers now send some messages directly to players' Half-Life consoles
-	clan tag validation for HLDM clans is now supported for game directories in the VALVE directory; the AG mod is also supported for HLDM clans (gamedir = AG)
-	fixed bug with parsing player names that had colons and periods in them
-	players are now only given a few tries to successfully receive an update (as opposed to endless uploads)
-	PB will accept rcon_passwords up to 63 characters in length now (limit was 31)
-	Linux version now traps all kill signals (i.e. ctrl+c) and exits cleanly
-	new LAN setting (LAN 0 or LAN 1 - default is 0) to cause the PB server to not try to contact the Master Server and also causes banning by IP rather than WONID for Required servers
-	2 new variables called BCMsg1 and BCMsg2 let Admins customize the informational text that PunkBuster broadcasts throughout gameplay; PB will automatically append either OPTIONAL or REQUIRED to the end of BCMsg1 before output and will append the IP/URL of the Monitoring Server to the end of BCMsg2 before output
-	the GameSay setting has been discontinued and replaced by the more robust FilterSay setting; it is described in detail in the sample pbsvhl.cfg included in the archive
-	added a new server+ command to add a server along with specific FilterSay setting just for that server; see the sample pbsvhl.cfg file for details
-	WONIDs have been added to violation logging
-	tag validation problems with the '<' character have been fixed
-	PB Servers now use the Digital Signature checking on PB Client and Patch files obtained from the Master Server
-	new setting called AuthPulse (default 300) that lets Admins have the list of Authenticated players sent directly to all players' consoles every specified number of seconds (set to 0 to disable this feature)
-	new setting called ViolPulse (default 300) that lets Admins have the list of Non-Authenticated players sent directly to all players' consoles every specified number of seconds (set to 0 to disable this feature) *NOTE* This list will include players who are receiving updates or who just joined, it isn't always just players in Violation although that will generally be the bulk of what is listed there
-	fixed a bug with the sending of status info to PB Clients when the Status button is pushed
-	added code to the Linux version to reduce (hopefully eliminate) zombie processes that build up and never get released which can cause Linux-based PB Servers to stop working properly after running for a few hours

new changes for beta version 0.926 (1.8.2001)
-	significantly changed the way the GameSay variable filters: now, GameSay 3 (Quiet mode) is completely silent; PB will send nothing via rcon say; GameSay 2 (Medium mode) sends all messages except Clan Tag Validations (although it does send Tag Mismatches and Removal Warnings)
-	fixed new bug introduced in v0.924 that caused recurring authentication attempts for some users and no authentication attempts for other users
-	the cheater.log should now be created and contain positive known cheat violations as documented in both win32 and Linux versions
-	(as a trial) the PunkBuster Server will no longer send rcon say messages in-game to tell players that it is "trying to connect" to them; it will still send the Violation #14 message upon a connection timeout but it is reworded to hopefully make more sense
-	addressed glitch with plist command that caused it to sometimes show the same player multiple times
-	PunkBuster will no longer try to re-auth or connect to players who are in a Violation status
-	once players are Authenticated they will be re-authenticated every 15 to 30 minutes; those time parameters will be admin adjustable in a future release

new changes for beta version 0.924 (1.7.2001)
-	player records are now discarded soon after they are no longer needed (as opposed to previous versions where player records were held until program end)
-	new password publishing feature added so that PB servers can be locked with a password that is optionally sent to PB clients when they press the List button; using this will prevent non-PunkBuster "aware" players from being able to join the server (note: we are not pushing or suggesting the use of this feature, only offering it for admins who wish to try it out)
-	new variable called PublishPw which defaults to 0 can be set to 1 from inside the pbsvhl.cfg file (or from the console) to enable the feature described above
-	re-prioritized message catigorizations for the 4 levels of Screen and File logging; less verbage is output for the lower level settings
-	removed much of output of 'raw binary' I/O data that is sent to / received from players and Game Servers, use 'Debug 4' in your pbsvhl.cfg or the command line if you prefer to see the extra 'old-style' logging; also when sending logs to us for support and troubleshooting, please use 'debug 4' mode to create the logs when possible so that we have as much low-level I/O as possible to work with
-	plist command now more useful since only current records are retained and also the status column more accurately describes each player's current status
-	addressed the issue of some non-PunkBuster running players not timing out for long periods due to certain routing problems
-	when a Game Server is empty, the monitoring PB server no longer sends broadcast messages or timelimit/timeleft queries
-	backslash glitch with the violator.log and cheater.log files fixed for Linux version
-	new Query Scripting feature is described in detail in section IV of this readme.txt file
-	new commands QueryStart, QueryStop, and QueryVar added to support the Query Scripting feature
-	new file type .pbq files to hold Query Scripts (sample.pbq included in the server archives)

new changes for beta version 0.922 (1.2.2001)
-	new command line statements added to match the buttons in the win32 gui screen (Update, Quit, Exit)
-	new additional log file called cheater.log includes only violations that are in the range of positive known cheat violations (the list of violation numbers is on the Support page of our website)
-	addressed the glitch that causes a failed "hand-off" when the Master Server updates PB Servers over the Internet
-	new format for log file names: YMMDDXXX where only the first character represents the year 0=2000, 1=2001, A=2010, etc.
-	midnight rollover is now correctly accounted for in naming new log files
-	new optional remote administration feature called Telnet access added to the system: a new cfg file called telnet.cfg holds passwords for remote access
-	new variable called MaxTelnet (default to 0) determines the maximum number (up to 8) of concurrent Telnet sessions that can be open for the PB Server
-	Linux version of PunkBuster now compiles from same source files as the win32 version and will be first released under this version number of 0.922
-	fixed bug that caused server to hang if http:// was in the MOTD variable
-	all binary characters are converted to an asterisk before being output to the screen
-	new Restart command added that causes the PB server to close itself down and re-run itself cleanly as though manually exited and restarted
-	new "keep alive" packets sent from server to client after successful authentication every 10 seconds (approx.) in an effort to fix connection losses between authentications
-	the ClientRequests variable has been dropped and players can no longer remotely request PB monitoring from the PB client, this feature is no longer useful since there is now a native Linux version and also telnet access which is a much more robust way to remotely admin a PB server
-	new logout (or logoff) command to disconnect from telnet sessions
-	fixed bug in parsing the servers.cfg file (extra spaces was causing corruption)
-	fixed bug with rcon ban commands to limit bans to 60 minutes

new changes for beta version 0.920 (12.19.2000)
-	fixed bugs that caused a PB server to keep pinging a game server after the rcon password was changed by the hlds admin
-	the PB server now has a sys tray icon that can be used to toggle when the window is hidden / shown
-	by using the +HID command line parameter in a shortcut or batch file, the PB server can be started in hidden mode (ex: pbsvhl.exe +hid)
-	a new patch update will be uploaded to clients only if they don't already have the latest version rather than before every single authentication
-	when an auto update fails during transmission, the server will break the tcp connection to force the client to reset after a brief timeout period
-	the remote monitoring feature no longer allows users to update info about servers being monitored
-	new variable setting created called PBURL that let's admins determine what gets broadcasted into the game as the PB Server's address (ex: PBURL tfc.friendly.com)
-	cheat violations now include both a numeric and a brief textual description in broadcast messages
-	cheat violation codes under testing are denoted that way
-	server should no longer crash after receiving updates from the Master PB Server

new changes for beta version 0.918 (12.8.2000)
-	only even numbered Server versions will be released as we will use odd numbers for internal testing
-	the variable BCMin can now be set up to 1200 to keep informational broadcasts to up to a forced 20 minutes apart
-	new variable GameSay for admins to control text output to Game Servers: 1=standard (default), 2=medium, 3=quiet
-	new variable BanType for LAN Servers so that bans are made by using the 'rcon addip' command instead of the 'rcon banid' command which doesn't work for LAN scenarios - if BanType is set to 0 (default), then 'rcon banid' is used; if set to 1, then 'rcon addip' is used (not fully tested yet)
-	PunkBuster icon added to the executable file
-	remote monitoring requests from PB Clients for Stopping a server will now require the valid rcon_password be sent with the request for it to be honored
-	the close confirmation box has been eliminated
-	if the server fails initialization upon launch then output is dumped into the file pbsvhl.err to help troubleshoot the problem

new changes for beta version 0.915 and 0.916
-	fixed the #104 errors
-	fixed the bug that was causing continual Patch downloads under win2k
-	PB Servers now broadcast the Internet IP rather than LAN IP for Servers behind a NAT device/proxy/firewall
-	the Client and Server can now be running together on the same machine (although they must run from separate directories)

new changes for beta version 0.914
-	fixed bug that was sometimes causing #10049 error connecting to Master Server
-	added extra double quotes in rcon kick and rcon banid commands to ensure proper parsing by certain mods
-	Master Server now only receives info about Game Servers that are actually being monitored
-	Master Server only reports servers that have been updated within the last 10 minutes (apprx) to keep the list "fresh"

new changes for beta version 0.913
-	added stop command. syntax: stop <id> used to stop monitoring a specific server
-	added start command. syntax: start <id> used to start monitoring a specific server
**NOTE: The <id> referred to above is the PunkBuster ID which can be obtained with the SLIST (Server List) command
-	fixed bug: some servers that were set to penalties=1 (COMPLIANCE: Required) were not kicking players in violation
-	fixed bug: Server was not recognizing auto updates of clients from Master PunkBuster server without a restart

