Table of Contents

csbuddy  

Summary

A Counter-Strike server log file monitor and administration tool.

Overview

CSBuddy is a tool designed to help Counter-Strike server owners, particularly those running AdminMod. It does two things: First, it maintains a queryable database of all players that have been seen on the server; and second, it filters the raw logs of a Counter-Strike server and distills them into a single CSBuddy log which shows only high-level activity such as excessive friendly fire incidents, admin activity, and players complaining about misbehavior or saying suspicious things.

This tool is built upon an included Counter-Strike log file parser which is provided in a simple derivable class.

Getting the software

The current version of csbuddy is 1.2.5.

The latest version of the software is available in a tarball here: http://www.alcyone.com/pyos/csbuddy/csbuddy-latest.tar.gz.

The official URL for this Web site is http://www.alcyone.com/pyos/csbuddy/.

Requirements

CSBuddy requires Python version 2.0 or greater.

License

This code is released under the GPL.

Setup

Your Counter-Strike server should be configured for maximum logging information. Put the following commands in your server .cfg file:

        log on
        mp_logfile 1
        mp_logdetail 3
        mp_logmessages 1

You should put csbuddy.py in a cron job or in some way that it runs regularly with the -S option pointing to your Counter-Strike log files directory. Every five minutes is a reasonable frequency, although the rate depends on the timelimit for your server maps and whether or not you allow map voting.

Files

CSBuddy, when running normally, maintains a set of files. By default the files are placed in the .csbuddy directory under the user's home directory, but this behavior can be changed with the -d option. The files are as follows and are updated whenever a sync is performed:

csbuddy.state
The state file, the main database. It loads this whenever queries are performed and saves it whenever it is synced against the log files directory.
csbuddy.names
This is a simple text file containing pairs of WONIDs and player names (the last name that was used) separated by a tab. This is designed for easy grepping since database queries can be slow.
csbuddy.log
This is the primary log file, the one that CSBuddy keeps writing to.
csbuddy.chat
This is a log of all player chat that takes place on the server, including player connects, disconnects, and map changes for references. This way activity on the server can be closely monitored.

Invocation

The following command line arguments are supported:

-V/--version
Print the version and exit.
-h/--help
A help summary is printed to stderr.
-b/--brief
When queries are performed, only basic information about each result is printed. This option only applies to queries.
-f/--force
Force full scan on the specified directory, don't take into account the last known log file seen or do end-of-year detection. Useful when doing bulk scans of log files.
-d/--dir (directory)
Specify the directory where CSBuddy will expect to find its data files. The default is $HOME/.csbuddy.
-s/--summary
Print a summary of the current data files and exit.
-S/--sync
The remaining arguments are treated as paths to directories which will be used to synchronize the database files.
-w/--won
The remaining arguments are treated as queries based on WONID.
-n/--name
The remaining arguments are treated as queries based on the most frequently used or last name that each player has used.
-N/--names
The remaining arguments treated as queries based on names which have ever been used by players.
-P/--patterns
The remaining arguments are treated as case insensitive substrings of names that have ever been used by players.
-i/--ip
The remaining arguments are treated as full dotted quad IP addresses (e.g., 1.2.3.4) which have been most used by a given player.
-I/--ips
The remaining arguments are treated as full dotted quad IP addresses which have ever been used by players. This will show all players which have ever used the specified IP address.
-J/--prefixes
The remaining arguments are treated as IP address prefixes (i.e., subnets) which any player has ever used.

Usage

CSBuddy provides command line help with the -h option, and version information with the -V option.

CSBuddy is run in two modes: Queries and syncing. Queries are performed on a preexisting database; syncing refreshes the database against the latest batch of log files. This is done by simply using the -S option:

        csbuddy.py -S /path/to/cstrike/logs

This will process any new logs, and update the abovementioned four files. To get a summary of the current database, use the -s option:

        csbuddy.py -s

Queries can be performed with the -w, -n, -N, -i, and -I options. The -w searches for the record corresponding to the unique WONID. -n and -i search for the most probable record corresponding to the specified name and IP address, respectively. -N and -I work analogously to -n and -i, except that the capitalized versions will print information on all matching records, rather than the most probable match.

This will retrieve information for the player with WONID 1111:

        csbuddy.py -w 11111

This will retrieve the most likely record for the player who has used the name "BadPlayer":

        csbuddy.py -n BadPlayer

This, on the other hand, will retrieve the records for all players who have ever used that name:

        csbuddy.py -N BadPlayer

Similarly, this will retrieve the record for the player who has most frequently used the IP address 1.2.3.4:

        csbuddy.py -i 1.2.3.4

However, this will retrieve the records for all players who have used that IP address:

        csbuddy.py -I 1.2.3.4

The -J option will retrieve records for all players with a given IP prefix:

        csbuddy.py -J 1.2.3

The -P option searches for all players that match a certain "pattern," meaning substrings independent of case:

        csbuddy.py -P phat

The -b option prints less information (for large matches):

        csbuddy.py -b -P neo

Log file entries

The distilled csbuddy.log file contains so-called "important" events. This is appended to over time; this is the primary feature of CSBuddy. The best way of watching this file is with tail -f.

The events that CSBuddy tracks are described below. When players are indicated, they are specified in curly braces with a WONID followed by a slash and then their current name.

POSSIBLE CRASH
A log file ended prematurely and suggests a crash.
FRIENDLY FIRE
The specified player shot and injured his own teammates during a map. The number of incidents (the number of shots that hit a friendly plus the number of friendly kills) is shown; the threshhold is set quite low so that claims of deliberate but not large scale TKing can be easily corroborated. Incident counts under 20 are nominal; above 50 usually indicate a problem with TKing, and above 100 indicates a situation totally out of control.
MAP START
The specified map started.
FLOODING
A player is flooding, by repeating the same thing over and over again.
ADMIN MENTIONED
The word "admin" was mentioned, often indicating questions on the part of the players about who the admins are or what they are doing.
PROSCRIBED KEYWORD
A player said a particular keyword that warrants examination. This includes complaint about cheating, team killing, flooding, kicking, or banning. Looking for complaints of team killing followed by high friendly fire incident counts is a good way to find TKers without too much overhead.
ADMIN MAP CHANGE
One of the admins changed the map with AdminMod.
ADMIN PUNISH
One of the admins punished one of the other players, by slapping, slaying, kicking, banning, gagging, or llama'ing him.
ADMIN COMMAND
One of the admins executed an arbitrary command.
ADMIN SAY
An admin made a statement to the players through the AdminMod facilities, such as say, ssay, csay, or tsay.
ADMIN ANNOTATION
Admins used the private admin_chat facility to communicate with one another.
HLGUARD FOUND/BANNED
HLGuard found or took action against the specified player, should HLGuard be installed.

Known issues

  • CSBuddy needs to be able to tell where the first log and the last log is. Unfortunately, Half-Life's log file naming sheme does not include the year, so if logs are left to accumulate for longer than a year, they will start to overwrite each other. CSBuddy works by filename only, so it cannot detect this case (though it can detect the case where the existing log files cross a date boundary). Because of this, it's important to occasionally clean out old files.

  • Due to buffering, the most recent log file is skipped in every scan. This means that CSBuddy will lag behind the current activity on the server, by a period of time that corresponds to how often it is run in a cron job.

  • Lookups are not at all fast when the database starts getting very large. This can be improved by breaking it into smaller databases, a step which has not yet been done.

Release history

  • 1.2.5; 2003 Apr 3. Include annotations for players connecting, disconnecting, changing names, and map changes in the streaming chat log file for reference; add force option (-f).

  • 1.2.4; 2003 Mar 16. Fix WONID parsing for cases where an invalid WONID is shown due to LAN play.

  • 1.2.3; 2003 Jan 2. Okay, the real fix for the end-of-year rollover bug.

  • 1.2.2; 2002 Dec 19. Fix bug in regular expression for parsing rcon and bad rcon messages.

  • 1.2.1; 2002 Dec 17. A fix for the end-of-year rollover bug. A mix of logfiles stradding the year boundary will now be handled properly, provided some gap in the months between exists.

  • 1.2; 2002 Nov 23. Add -J option for finding by IP prefix (subnet); default data files directory changed to $HOME/.csbuddy instead of $HOME; improved invocation reference in documentation.

  • 1.1; 2002 Nov 10. Convert commands to lowercase before checking; add -b option for brief reporting; add -P option for checking case insensitive substrings; use -V option for version information.

  • 1.0.3; 2002 Oct 14. Bugfix: Regular expression dictionary had ambiguous cases which showed up in later versions of Python (punish commands not appearing properly).

  • 1.0.2; 2002 Oct 10. Support for kick and secure kick messages; save csbuddy.state file as binary to improve performance.

  • 1.0.1; 2002 Aug 27. Minor bugfix: Normal say events were not being reported in the .chat log file.

  • 1.0; 2002 Aug 18. Initial release.

Author

This module was written by Erik Max Francis. If you use this software, have suggestions for future releases, or bug reports, I'd love to hear about it.

Version

Version 1.2.5 $Date: 2003/04/03 $ $Author: max $

Modules and Packages   
csbuddy

Monitoring system for Counter-Strike logs.

cslog

Counter-Strike log parsing system.


Table of Contents

This document was automatically generated on Thu Apr 3 02:05:27 2003 by HappyDoc version 2.0.1