BW-Admin

BW-Admin Documentation

Current Version: 1.72

Barrysworld Bot Detection & Admin Plug-In DLL
For Quake2 & KingPin

(or BW-Admin for short :)

DOWNLOAD Current Version

Windows 95/98/NT bw-admin.zip

Linux (Linux: glibc v2.1) tar.gz archive

Linux (Linux: libc) tar.gz archive

FreeBSD (ELF Binary Format) tar.gz archive

Sparc Solaris tar.gz archive

Features:

A transparent DLL that adds to any existing Server MOD: Logged Bot detection and kicking. Rate and 'cl_maxfps' capping. Player IP and NAME banning. Server MOTD and other Admin options. Configurable item/weapon spawning. Reserving nicks to specific IP's. Flood protection and speech filtering for offensive keywords.

For those interested in writing their own plug-in then here is some example code illustrating how to do it:
Download Plug-In Source Code
Latest Version Info:

04/06/00 v1.72
Changes:

New version detects latest speedbot & ratbot (thanks to Killerbee, author of Q2Admin).

Sorry for the delay but I've been very very busy moving house, and starting a new job which means I do not have the same amount of free time to dedicate to my gaming code.

Zarjazz.

.
.

23/10/98 v1.00 : Released first public version.

Bug Reporting:

If you have problems with the admin dll causing server crashes in a reproducable manner can you please enable all the bw-admin and Q2 logging options, wait for another crash and then send me all the logfiles. This will greatly help me track down any remaining bugs that I have been unable to find. Also, many thanks for all the feedback during the last few releases from too many people to mention. Without all the suggestions I would of been unable to add all the useful new options :)

Installation:

Windows Q2 3.20+: Unzip the file BW-Admin.zip into your game server directory (Quake2/, KingPin/).

Linux & Solaris : For each server mod you want to use the admin software with, rename the original mod's gamei386.so / gamesparc.so file (eg gamei386.so.real). Then copy the admin gamei386.so / gamesparc.so file into the mod directory and put the name of the renamed file into the bw-admin.cfg file dll = line (see Configuration).

Automatic Updates:

To enable the auto download & update features you will need to have installed WGet onto your system. WGet is normally a standard package on most modern Linux installations but it is fairly straight forward to compile the source code if you do not have it already on your server. Links to Windows 98/NT versions are on the WGet homepage or you can download the WIN32 executable from HERE.

To configure WGet for use with BW-Admin:
on Unix system ensure it is installed in a standard path eg /usr/bin
on Windows, copy wget.exe to the directory where your server executable file is found.
Then in the bw-admin.cfg file set "have_wget = 1"

Read the instructions for the rest of the auto_* configuration settings belows

Configuration:

The DLL attempts to read a file called bw-admin.cfg from the root game server directory, and then the actual game mod directory. So you can specify global settings for all servers and then override specific configuration settings for individual servers. If you run multiple servers from a single directory and need to use seperate configuration files for each server, then you can override the name of the configuration file by using the command line option +set bwcfg filename.

The file syntax is as follows : < option > = < value >
where the full option list is ...

NOTE: Default settings are shown in bold.

Server Settings

dll = [name] Tells the Admin DLL what the renamed original "gamei386.so" to be loaded is called. MUST be given on LINUX and Solaris systems.

motd = [file-name] Specifies a file containing text to display to connecting players. The DLL first looks in the mod directory and then the base Q2 directory for the file. Default = No MOTD.

stuff = [file-name] Specifies a file containing a list of commands to 'stuff' to a user when they connect and on each map change. eg "allow_download_maps 1". Each command should be on a seperate line.

itemspawns = [value] (Q2 Only) Sets the item spawning flags. Default = 0 (see below).

Bot Protection

botcheck = [0/1] 1 = Detect bots. 0 = Do not use bot detection code.

botkick = [0/1] 1 = Kick any detected bots. 0 = Just log offenders name/ip.

strict = [0/1/2] (Q2 Only) This option checks the incoming connection and checks if the client looks to be using anything a plain vanilla (normal) Win32 Quake2 client.
0 = Allow all connections to the server.
1 = Ultra strict. Prevents anything but a connection that acts like the plain Quake2 executable to connect.
2 = Strict. Prevents any "dubious" clients from connecting to the server. This is mainly designed to stop any bot-like proxies but allow *some* NAT users to connect.
WARNING: Any strict setting other than 0 may prevent legitimate users from connecting to the server, currently the Win 98 SE internet sharing option seems to cause problems.

reject_msg = [0/1] Tells a client why they were refused connection by BW-Admin (eg IP/Name Banned). 0 = No rejection message.

Player Voting

p_limit = [value] Sets the minimum number of players on the server needed before player voting can be started. Default = 0 (voting disabled).

p_percent = [value] The percentage of Yes votes needed for the voting to succeed must be greater than this value. Default = 50.0

p_kickban = [0/1] If a player is kicked by a vote, ban them from the server.

Client Settings

maxfps = [value] Sets the maxfps for the server. If not specified default = no limit.

capkick = [value] Due to technical reasons the maxfps capping is not instantaneous so a server admin can be strict enforcing the maxfps capping. Specify the # of times the client can change their cl_maxfps setting per map before getting kicked from the server. Default = 0 (no kicking).

maxrate = [value] Sets the maxrate for the server. If not specified default = 25000.

maxping = [value] Sets the maximum allowed ping on the server (anyone whose ping goes above this value will be kicked from server). Default is no limit. WARNING: Use with caution since this may occasionally kick lagged players!

minping = [value] Sets the minimum allowed ping on the server (anyone whose ping goes below this value will be kicked from server). Default is no limit.

spectators = [0/1] Disallow / Allow Q2 3.20 type spectators on the server. Turning off spectators (0) also fixes the annoying "invisible player" exploit.

Misc Settings

admin = [password] Sets the DLL server admin password. Default is to disable the server admin option.

super = [password] Sets the DLL server supervisor password. Default is disable option.

auth = [file] Specifiy the file with the list of authorized (password protected) nick's used on the server

exec = [file] If this key is set then the DLL will tell the server to 'exec cfg-file' as if type at server console. This command is only activated on the 1st ever client connection to the server. DO NOT put a 'map ..' command in this 2nd server config or you will put the server into an endless loop!!

banner = [0/1] 1 = Display banner text. 0 = No banner text.

use_say_team = [0/1] Disable / Enable the 'say_team' command.

reload = [0/1] 1 = Reload the admin configuration after every map change. 0 = Do not reload.

overflow = [0/1] (Q2 Only) Enable a work around for a server that get "SZGetSpace" errors only when using the dll. This is a bug with certain mod's and not the dll really.

Flood Protection

flood_lines = [value] Specifies the maximum number of lines allowed within a set time. Default = 0 (no flood protection).

flood_time = [value] Specifies the allowed time used with flood_lines. Default = 0 (no flood protection).

flood_ban = [value] Set the number of seconds a client is unable to speak if flood protection is enabled. Default = 5.

Logging Options

logging = [0/1/2] Logs Bot detection and several admin notices to a file called "BW-Admin.log" in the mod directory. 0 = No logging. 1 = Create new log on server initialization. 2 = Append to existing log.

track_connect = [0/1] If 1 then the DLL logs all (attempted) player connections to the file "BW-Tracking.log" in the mod directory.

track_disconnect = [0/1] If 1 then the DLL logs all players disconnecting from server.

track_renames = [0/1] If 1 then the DLL logs all player name changes.

track_refused = [0/1] If 1 then the DLL logs all failed player connections and if possible the reason why.

Auto Download

have_wget = [0/1] If 1 then the DLL will use 'WGet' to check for updates and if enabled, download and install new versions of the DLL. 0 = disable or no 'WGet' installed.

auto_download = [0/1] 1 = the DLL will download the updated version to the same name/location as the current DLL but with an extention of ".new". If 0 the DLL will not download.

auto_install = [0/1] If 1 the current DLL will be copied to a backup file with '.bak' extension and the new DLL will be moved into it's place. NB This does NOT mean the new dll is loaded. This will only come into effect when the server is restarted. 0 = the DLL will not install the new DLL.

auto_restart = [0/1] If 1 then if an updated DLL has been installed then the server will be terminated. This option assumes you have some sort of automated server restart upon process termination. 0 = the DLL will not kill the server.

The whole configuration (including bans) can be reloaded at anytime using the server console / rcon command sv reload.

Item Spawning: (Q2 Only)

Depending on the value of the 'itemspawns' flag specified in the DLL config file it is possible to disable certain items. The flags for each item are as follows:
# SHOTGUN		1   
# SUPER_SHOTGUN		2   
# MACHINEGUN		4   
# CHAINGUN		8   
# GRENADES		16  
# GRENADE_LAUNCHER	32  
# ROCKET_LAUNCHER	64  
# HYPERBLASTER		128 
# RAILGUN		256 
# BFG			512 
# QUAD			1024
# INVULNERABILITY	2048
# POWERSHEILD		4096
So if you wanted to disable Railgun and Quad: itemspawns = 256 + 1024 = 1280

NOTE: This does not work with all mods and may even crash the server. You have been warned! :)

Player Voting:

Once the voting is enabled (see Configuration) the follow command(s) are available to the players:

Player Kicking: A clients starts a vote by typing p_kick "player" where player is the nearest player name it can match against

so if they wanted to kick [IAM]A-Lamer, they could just type p_kick lamer or p_kick [iam] and so on.

All users then toggle their vote (default = NO) by using the command p_vote.

After approx 60 second, the votes are counted and the player kicked if voting passed.

Authorized Nick's:

If the "auth = .." option is set in the configuration file, then the dll will attempt to read a file of the following format:
password "client name" (the quotes are required)
Where password is a single string of ascii characters, and client name is matched case and high-ascii insensitive. Anyone attempting to connect to the server with a password protected nick will be refused, as will be anyone who changes their name while already on the server.

To use such an authorized name, the client should type: cl_nick password and the relavent nick will be automatically assigned.

Bans File:

The DLL tries to read the file "server_bans.txt" from the root Q2 directory and also the mod directory. If both files exist then both files are read. The file contains a list of all the server bans. The format of each ban is as follows:

IP Bans:
IP: [+/-] xxx.xxx.xxx.xxx[/0-32] [#N] is the structure of the ip ban. The [...] fields are optional.
[+/-] : - denotes refuse access to this address, + means allow access. Default = -
[/0-32] : specifies the subnet mask. Default = 32
[#N] : only allow N connection from this address (only relevant if the '+' is flag used). Default is no limit on connection count.

NOTE: The lower the IP Ban is in the bans file the high the priority (ie overrides any previous bans). Examples:

IP: - 148.88.88.0/24
IP: + 148.88.88.128/28

This list first bans the c-class subnet 148.88.88.* but then allows access from some subnet of that address.

IP: - 0.0.0.0/0
IP: + 127.0.0.1 #1
IP: + 10.0.0.0/8 #10
IP: + 128.56.0.0/16

This list first bans ALL connections then allows 1 connection from the localhost, 10 from the a-class subnet 10.* and allows any number of connections from the b-class subnet 128.56.*

NAME Bans:
NAME: text will ban anyone whose name contains the keyword text. The comparision is case insensitive and treats high ascii (colored text) as normal low ascii characters. Also anyone who changes their name during the game and the new name matches a ban will be kicked from server.

FILTER Bans:
FILTER: text will perform a comparision similar to the Name ban system except that this searchs all client speech and if it contains a keyword text the offending line will not be received by any other player.

ALIAS Bans:
ALIAS: [name] [ip] will only allow someone to use the alias name if they connect from the specified host. The name and ip follow the same rules as the IP and Name bans apart from the ip ignores the [+/-] and the [#] flags.

Examples:

ALIAS: Zarjazz 127.0.0.1
ALIAS: Zarjazz 195.65.0.0/16

The will only allow someone to use the nick 'Zarjazz' if they connect from the localhost or the b-class subnet 195.65.*
Note: at the moment, due to certain limitations, name must be a single string of text and contain no spaces. The name comparision must be an exact match (case and high ascii insensitive)

New bans can be added dynamically to the server bans file using the commands sv addipban [ip] and sv addnameban [name].

The current loaded bans list can be displayed using the command sv bans.

Server Admins:

A connected player gains server admin status by typing at the console sv_admin [password]. If the password matches the DLL admin or supervisor password then that client has the option of using the following commands:

sv_ip [name] List the IP of user 'name'
sv_kick [text] Kick any player whose name contains keyword "text" (like a NAME Ban but not added to server bansfile). Also available at server console using sv kick.
sv_lock Toggle server lockout (stop any new clients connecting). Also available at server console using sv lock.
sv_mute [time] [text] Enables mute on any player whose name contains keyword "text" for "time" seconds.
sv_stuff [player] [cmd] Stuffs a command to a specific player. Also available at server console using sv stuff.
sv_addipban [ip] Add IP Ban to server bansfile.
sv_addnameban [name] Add NAME Ban to server bansfile (also kicks any connected clients who match ban).
sv_exec [file] Exec's the config file on the server as if the admin had typed 'exec file' at the console but without needing rcon/console access.

Note: A supervisor is not able to add new server bans but all other commands are available

Credits:

Thanks to DBs for constant pestering, bug testing and forwarding some example code AFTER I'd already finished the first version :)

Special thanks to Andreas Banze for useful suggestions and feedback.

One of the bot detection routines was based on code supplied by Riv (riviera@earthling.net)

==================================================
Original idea based on ZKick
- anti-ZBot Proxy Game Module for Quake II
by Avi Rozen (Zung!)
==================================================

==================================================================================

mailto:zarjazz@barrysworld.com | http://www.barrysworld.com/zarjazz

DOWNLOAD Current Version
Windows 95/98/NT	bw-admin.zip
Linux (Linux: glibc v2.1)	tar.gz archive
Linux (Linux: libc)	tar.gz archive
FreeBSD (ELF Binary Format)	tar.gz archive
Sparc Solaris	tar.gz archive

Server Settings
dll = [name]		Tells the Admin DLL what the renamed original "gamei386.so" to be loaded is called. MUST be given on LINUX and Solaris systems.
motd = [file-name]		Specifies a file containing text to display to connecting players. The DLL first looks in the mod directory and then the base Q2 directory for the file. Default = No MOTD.
stuff = [file-name]		Specifies a file containing a list of commands to 'stuff' to a user when they connect and on each map change. eg "allow_download_maps 1". Each command should be on a seperate line.
itemspawns = [value] (Q2 Only)		Sets the item spawning flags. Default = 0 (see below).
Bot Protection
botcheck = [0/1]		1 = Detect bots. 0 = Do not use bot detection code.
botkick = [0/1]		1 = Kick any detected bots. 0 = Just log offenders name/ip.
strict = [0/1/2] (Q2 Only)		This option checks the incoming connection and checks if the client looks to be using anything a plain vanilla (normal) Win32 Quake2 client. 0 = Allow all connections to the server. 1 = Ultra strict. Prevents anything but a connection that acts like the plain Quake2 executable to connect. 2 = Strict. Prevents any "dubious" clients from connecting to the server. This is mainly designed to stop any bot-like proxies but allow some NAT users to connect. WARNING: Any strict setting other than 0 may prevent legitimate users from connecting to the server, currently the Win 98 SE internet sharing option seems to cause problems.
reject_msg = [0/1]		Tells a client why they were refused connection by BW-Admin (eg IP/Name Banned). 0 = No rejection message.
Player Voting
p_limit = [value]		Sets the minimum number of players on the server needed before player voting can be started. Default = 0 (voting disabled).
p_percent = [value]		The percentage of Yes votes needed for the voting to succeed must be greater than this value. Default = 50.0
p_kickban = [0/1]		If a player is kicked by a vote, ban them from the server.
Client Settings
maxfps = [value]		Sets the maxfps for the server. If not specified default = no limit.
capkick = [value]		Due to technical reasons the maxfps capping is not instantaneous so a server admin can be strict enforcing the maxfps capping. Specify the # of times the client can change their cl_maxfps setting per map before getting kicked from the server. Default = 0 (no kicking).
maxrate = [value]		Sets the maxrate for the server. If not specified default = 25000.
maxping = [value]		Sets the maximum allowed ping on the server (anyone whose ping goes above this value will be kicked from server). Default is no limit. WARNING: Use with caution since this may occasionally kick lagged players!
minping = [value]		Sets the minimum allowed ping on the server (anyone whose ping goes below this value will be kicked from server). Default is no limit.
spectators = [0/1]		Disallow / Allow Q2 3.20 type spectators on the server. Turning off spectators (0) also fixes the annoying "invisible player" exploit.
Misc Settings
admin = [password]		Sets the DLL server admin password. Default is to disable the server admin option.
super = [password]		Sets the DLL server supervisor password. Default is disable option.
auth = [file]		Specifiy the file with the list of authorized (password protected) nick's used on the server
exec = [file]		If this key is set then the DLL will tell the server to 'exec cfg-file' as if type at server console. This command is only activated on the 1st ever client connection to the server. DO NOT put a 'map ..' command in this 2nd server config or you will put the server into an endless loop!!
banner = [0/1]		1 = Display banner text. 0 = No banner text.
use_say_team = [0/1]		Disable / Enable the 'say_team' command.
reload = [0/1]		1 = Reload the admin configuration after every map change. 0 = Do not reload.
overflow = [0/1] (Q2 Only)		Enable a work around for a server that get "SZGetSpace" errors only when using the dll. This is a bug with certain mod's and not the dll really.
Flood Protection
flood_lines = [value]		Specifies the maximum number of lines allowed within a set time. Default = 0 (no flood protection).
flood_time = [value]		Specifies the allowed time used with flood_lines. Default = 0 (no flood protection).
flood_ban = [value]		Set the number of seconds a client is unable to speak if flood protection is enabled. Default = 5.
Logging Options
logging = [0/1/2]		Logs Bot detection and several admin notices to a file called "BW-Admin.log" in the mod directory. 0 = No logging. 1 = Create new log on server initialization. 2 = Append to existing log.
track_connect = [0/1]		If 1 then the DLL logs all (attempted) player connections to the file "BW-Tracking.log" in the mod directory.
track_disconnect = [0/1]		If 1 then the DLL logs all players disconnecting from server.
track_renames = [0/1]		If 1 then the DLL logs all player name changes.
track_refused = [0/1]		If 1 then the DLL logs all failed player connections and if possible the reason why.
Auto Download
have_wget = [0/1]		If 1 then the DLL will use 'WGet' to check for updates and if enabled, download and install new versions of the DLL. 0 = disable or no 'WGet' installed.
auto_download = [0/1]		1 = the DLL will download the updated version to the same name/location as the current DLL but with an extention of ".new". If 0 the DLL will not download.
auto_install = [0/1]		If 1 the current DLL will be copied to a backup file with '.bak' extension and the new DLL will be moved into it's place. NB This does NOT mean the new dll is loaded. This will only come into effect when the server is restarted. 0 = the DLL will not install the new DLL.
auto_restart = [0/1]		If 1 then if an updated DLL has been installed then the server will be terminated. This option assumes you have some sort of automated server restart upon process termination. 0 = the DLL will not kill the server.