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