QBan - A Starsiege Ban Tool for Server Operators
Version 0.1, last modified April 30, 2001.

FEATURES

- Ban list persists across server resets in an easy-to-edit file.
- Ban/unban from client (with password) or server consoles.
- Auto-bans players with Nasty Names ("<R" or "<Y" anywhere in them).


OVERVIEW

Starsiege has fairly primitive built-in support for banning.  You can kick()
a player, after which they can freely rejoin; or you can ban() them, which
kicks them and then refuses connections from their IP address for a certain
time.  Unfortunately the server forgets bans when it restarts.

QBan lets you specify addresses to permanently ban.  You can add to the list
without restarting, and because it's stored in a file your list stays intact
even after the server restarts.  Your list may even grow on its own.  When
one of Starsiege's most recent form of troublemaker shows up with unfriendly
codes in his name QBan automatically shows him the door and adds him to it's
list.  You don't have to lift a finger.

Beyond that I encourage you to use QBan sparingly.  Save it for vandals and
other true sociopaths.  Use kick(ID) or ban(ID,minutes,msg) to deal with
ordinary idiots.  First of all you don't want a QBan list with hundreds of
entries, its unwieldy; and second, IP addresses are not a perfect indication
of identity.


INSTALLATION

Remember to make backup copies of files BEFORE you alter them!  The following
files need to be installed:

  File              Destination
  qbanlist.cs       starsiege
  qban.cs           starsiege/scripts
  qban.txt          starsiege/scripts
  * DMstdlib.cs     starsiege/multiplayer
  * CTFstdlib.cs    starsiege/multiplayer

* These files will replace your stock copies. Make a backup so you can
uninstall if necessary.

You MUST also edit starsiege/scripts/autoexec.cs and add a new last line:

  if ($CmdLineServer) exec("qban.cs");

This runs qban.cs whenever a dedicated console server is started, which loads
the ban list and sets up the commands for admins to use.

qban.cs contains all the control logic and a few parameters you may want
to change.  You can edit qban.cs to enable CLIENT ADMINISTRATION (see below)
or maybe alter other settings.  The possibilities should be clear from
comments in the code.  Please, if you don't understand something in there
don't change it, you shouldn't really need to.

You may want to enable server logging, you could find the information useful.
Starsiege logs mission cycles as well as player names and addresses, and QBan
logs its actions, including the activities of client admins.  To enable
logging edit starsiege/scripts/autoexec.cs and make sure the following line
is uncommented (remove any leading //) so it looks like:

  $missionLogFile = "log.txt";

If you already have a list of IPs you'd like to ban read THE BAN LIST section
below for directions.

QBan does not fully protect servers and clients from Nasty Names. The damage
is done before QBan can kick them.  To mitigate the harm get and install the
M.I.B. Hack Immunity Patch (see CREDITS below), and spread the word about it
to your players.

The DMstdlib.cs file in qban.zip is necessary only if you host DM or TDM
games, CTFstdlib.cs is necessary only if you host CTF.  If those are all you
care about you can skip to the next section.

If you host other types of games (MP Campaigns, Harvester, Overrun, etc) or
have already customized your DMstdlib.cs or CTFstdlib.cs for some reason and
don't want to replace them, then you'll need to do just one simple thing:
find the function called player::onAdd() that the game uses and add a call
to Qcheck() as the new first line like so:

  function player::onAdd(%this)
  {
      if (!Qcheck(%this)) return;
      player::onAddLog(%this);
      ...

Make sure what gets passed to Qcheck() is a PLAYER ID.  If your games don't
define a player::onAdd() function then you must make one like this:

  function player::onAdd(%pid) {Qcheck(%pid);}

You can put this whereever the game's onMissionStart() or onMissionLoad() are.

For Football edit player::onAdd in multiplayer/Starsiege_Football.cs.

For WAR edit player::onAdd in multiplayer/WAR_Martian_Standoff.cs. Likewise
for any other WAR_*.cs script you might use.

If players with IPs on your list aren't being automatically kicked when they
join it's most likely because the call to Qcheck() is wrong.  If you get
stuck getting this to work consult the SUPPORT section below.


THE BAN LIST

QBan stops anybody with a static IP address cold, but many ISPs assign
addresses dynamically.  That means some players can just hang up, reconnect,
and shazaam they have a new IP address.  QBan can deal with them too, it's
just a bit more tedious.

The names and IP addresses of banned players are stored in qbanlist.cs,
which you can alter using your favorite text editor, eg. Notepad.  While the
server is running this file is automatically rewritten whenever the ban list
is changed by an AUTOMATIC OPERATION or COMMAND as described below.

To manually alter your ban list just add or remove lines of the form:

  $Qnm[$Qn]="Script Kiddie #63"; $Qip[$Qn]="IP:192.168.1.102:0"; $Qn++;

The name between the first set of quotes is optional.  Don't remove the $Qnm
stuff, but the name can be "".  Names are purely for the benefit of
organizing and sharing your list.  Players are not rejected by name, and
they never should be because imposters would wreak havoc.

The IP between the second set of quotes is critical.  Note the port should
always be ":0".  It means any port will match.  If any of the other octets
in the address are 0 they too will match any value.  Often only the last
octet changes in a dynamic address, so something like "IP:192.168.1.0:0"
(which bans all 255 addresses in the 192.168.1 subnet) can be useful.
The Qbansubnet() command does this, and you can even set the other octets
to 0 by editing qbanlist.cs manually.  Eventually you can stop even the most
tenacious dynamic troublemaker.  Just remember that the broader the address
range the more likely you'll be banning innocents too.  QBan is so easy to
use you can have fun smacking down dynamic troublemakers one address at a
time.  Please do so.  Hopefully you'll never need to ban a whole subnet.

If you edit qbanlist.cs while your server is running you can type:

  Qload();

in the server console to have the new list take effect.


AUTOMATIC OPERATION

Once QBan is installed alot of what it does is automatic.  Most important
QBan kicks any player that joins with an IP address matching an entry in
your ban list.  If they're not in the list QBan checks them for a Nasty
Name.  If a "<R" or "<Y" is found they are kicked and added to the ban list.
If they have a Stealth Name (begins with "/") QBan will announce to all
players that they have joined.


COMMANDS

QBan can be controlled from the server console or from the console of any
client who has your QBan password.  The following commands are supported.
Only the playerlist() and remoteEval() commands can be used on clients, the
rest are work only in the server console.

playerlist();

  Lists all player names and IDs.  Once you have an ID you can use...

Qban(ID);                     Example: Qban(2050);
remoteEval(2048,Qban,pw,ID);  Example: remoteEval(2048,Qban,"shh",2050);

  The player's name and IP address are added to the ban list and the player
  is kicked with ban(). For 10 minutes the server will not accept connections
  from that IP.  If they come back after 10 minutes with the same address
  Qcheck() will just ban() them again.  If they have a new address...lucky
  you!  You get a chance to smack them again.  If you get bored use...

Qbansubnet(ID);
remoteEval(2048,Qbansubnet,pw,ID);

  Just like Qban except it bans all 255 of the addresses most similar to the
  player's.  One or more of these will likely stop any troublemaker, but it's
  a bit ham-handed.

Qbanname(name);                    Example: Qbanname("Taarna");
remoteEval(2048,Qbanname,pw,name); Example: remoteEval(2048,Qbanname,"shh","Taarna");

  If the player has a simple name you can try this command. Don't forget to
  put quotes around name.  Qbanname checks the names of all current players,
  and any that match exactly (case-sensitive) are passed to Qban.

Qbanlist();
remoteEval(2048,Qbanlist,pw);

  Displays the ban list.  This command may be useless or even cause trouble
  if your list gets very long.  But it's handy to get an N to use with...

Qunban(N);                     Example: Qunban(4);
remoteEval(2048,Qunban,pw,N);  Example: remoteEval(2048,Qunban,"shh",4);

  Removes entry N from the list.  Just zapped the wrong guy?  This undoes
  some of the damage.  The player must still wait 10 minutes for ban() to
  wear off.  Don't forget to apologize if they come back.

Qinfo();
remoteEval(2048,Qinfo,pw);

  Displays version and number of entries in the list.

ban(ID,min,msg);                    Example: ban(2051,10,"DUR!");
remoteEval(2048,ban,pw,ID,min,msg); Example: remoteEval(2048,ban,"shh",2051,10,"DUR!");

  Gives client admins a plain old (non-permanent) boot.  min is how long
  in minutes.  msg is the message the bootee gets, don't forget the quotes.

The "pw" in any remoteEval() command must specify the correct password.
Whether it's just another troublemaker or a fumble fingered admin, too many
mistakes and the client gets auto-banned.  Passwords are case-sensitive.


CLIENT ADMINISTRATION

Client access is disabled by default.  To enable it you must edit qban.cs and
specify a password.  Find and change the line that says:

  $Qpassword = "";

to something like

  $Qpassword = "shh";

Then share this password only with those players you want to be able to use
QBan.  Note: only the COMMANDS listed above that involve remoteEval() are
made possible by this password, it does NOT enable the client to run
arbitrary commands on your server.

The client's console must be enabled.  To do so edit
starsiege/scripts/autoexec.cs and find the following lines near the top:

  if ($me::enableMissionEditor)
     Console::enable(true);

Comment-out the first line like this:

  //if ($me::enableMissionEditor)
     Console::enable(true);

Once the console is enabled you can toggle it on and off with the ~/` key.


SUPPORT

I prefer questions, bug reports, and suggestions be posted to the Editing and
Scripting forum (navigate from http://community.sierra.com/).  This way
everybody can see what the issues are, as well as the answers.  Also, if I
"wander off" from Starsiege there are many other capable and helpful
scripters there who might answer.  If you find a serious problem and
absolutely must contact me you can send email to pgarpincushion@geocities.com.
Do me a favor and reread this documentation again to look for an answer first.

Visit http://www.geocities.com/SoHo/Nook/9351/maps/ for more Starsiege stuff.


DISTRIBUTION

Feel free to share QBan with anyone who wants it.


CREDITS

QBan was written, tested, and documented by [OF]Pincushion.

Several important features were made possible by the generous contribution
of ideas and source code by others.  I thank them for sharing.

The persistent dynamic ban is possible thanks to Orogogus, who figured out
the export()/fileWrite() trick it relies on.

Dull's strAlignR helps catch the nasty bits in player names.

Client administration is possible thanks to remoteEval(), which was first
revealed by Dr. Awkward and rescued from obscurity by Orogogus.  Dull's
PlayerAdmin package (see http://www.geocities.com/imverydull/Starsiege.html)
is a great example of it's use.

Thanks to M.I.B. for sharing their Server-Crashing Hack Immunity Patch,
a chat sensor script that nullifies the effect of Nasty Names.
http://www.geocities.com/ss_mibhq/Website/download.html