This page is part of an archive of the original QSmack website.
Most external links and a few download links don't work anymore.
To exit this archive, use the top/side navbars or return to the QSmack page.

QSmack Ban File Format

Here is an example of a ban file that bans a single IP address, two sets of IP addresses, and any names that contain carriage return or newline characters:

ban_ip      1.2.3.4
ban_ip      1.2.3.*
ban_ip      157.22.*.*
ban_exclude 157.22.179.*
ban_name    [\r\n]
ban_color   13 4
ban_color   4  13

As you see, you can ban players based on either their IP address, name or color. IP addresses can contain asterisks for wildcards. For matching player names, you use regular expressions. If you have no idea what a regular expression is, ummmm, well you can read this pretty good explanation of how they work. (Although that explanation says that regular expressions are case-insensitive, while ours are actually case-sensitive.)

If you're just starting to get your ban file together and want to test it before you actually kick anybody, here is what you do. You can set the admin password impulses to be wrong on purpose in the QSmack config file. In this way, QSmack will still perform the IP and name matches, but will be unsuccessful in kicking anybody because it hasn't gained admin privileges. You can see which player's IP or name is matching because QSmack prints a message to its log everytime a match occurs.

Banning by IP Addresses

A entry in the ban file for an IP address should have the keyword "ban_ip" followed by an IP address or address pattern that should be no more than 15 characters long. Whitespace is ignored.

First of all, you can just enter an IP address as the argument for "ban_ip", and that will ban that one address. (This is also what happens when you ban a player from within the game.) But, if you like, you can also ban whole slews of IP addresses with a single ban file entry. Eradicate entire subnets! Or domains! You can do this by using an "IP address pattern" instead of just an address.

The IP address patterns are not regular expressions like you can use for banning by name (as described below). Since IP addresses are fairly simple beasts -- just numbers and dots -- the patterns you use to match them are simple as well. There are no special characters except for the asterisk ("*") wildcard, which will match any octet (an "octet" is the sequence of digits between periods).

This means that

ban_ip     1.2.3.*

will ban any IP address that starts with "1.2.3". Regardless of what is in the final octet. This will, for example, usually take out at least one subnet, something you might want to do if a whole group of losers descend on your server from neighboring machines (as in a computer lab). This subnet may, of course, also include some completely harmless players. You have to make a judgement call when deciding to ban IP addresses using wildcards.

We know that a real weakness of this scheme is that you can't easily express a ban for IP addresses

1.2.3.0 through 1.2.3.127

The IP address masking scheme used by Quake World is superior in that respect and we would consider changing it if enough people asked. But it may be more capability than you need; the simple asterisk wildcard has worked fine for us.

Final note about IP addresses and Quake: Quake never puts unnecessary leading zeros in any octet. You will never see an address like "1.2.3.004"; instead, you would see "1.2.3.4".

Excluding IP Addresses from banning

Any IP address or wildcarded IP address can be excluded from normal IP banning. This is accomplished with the "ban_exclude" command in the banfile. The syntax for this command is the same as the "ban_ip" command described above.

This is generally useful if an entire subnet has been banned, but you want to admit individual IP addresses. An example of this is the following:

ban_ip      1.2.3.*
ban_exclude 1.2.3.6

Note that a player that has an excluded IP address can still be banned for their name or colors.

Banning by Player's Names

A entry in the ban file for a name should have the keyword "ban_name" followed by a regular expression that should be no more than 100 characters long. Whitespace is ignored. To include spaces in your regular expression use the code '\d32' as explained on the special characters page.

For those that really want to know, you can specify any valid POSIX extended regular expression. Please note that the regular expressions from the ban file are passed through a "string processor" before they are passed to the regex interpreter. It is during this step that a "\n" is converted to a newline character and a "\d32" is turned into a space. This means that to match special characters you have to double escape them. For example, to match against an actual period ".", you have to specify "\\." in the regex since the string processing will remove the first backslash.

When you come across someone you want to ban, use their IP address, not their name. When someone is banned, usually the first thing they try is to change their name and re-enter the game. If you ban them by name, they will be successful! At C9, we use the name banning function to keep people from using names that have certain characteristics. People whose names have newlines or carriage returns in their names are annoying because it messes up the way that kill and say messages are seen by all the players. We believe that these offending players are doing this on purpose to be annoying, so we ban them. We could also see banning people whose names have particularly offensive tones to them (the "N word" comes to mind).

Banning by Color

Banning by color was primarily added to allow admins of CTF servers to eliminate cross dressing. A entry in the ban file for a name should have the keyword "ban_color" followed by two numeric arguments from zero to thirteen inclusive (the valid quake colors). The first argument is the shirt color and the second is the pants. Both must be specified. To eliminate cross dressing on a CTF server that allows red or blue teams, add the following lines to your ban file:

ban_color  13 4
ban_color  4  13

A note on banning by color. Do not ban all white players (colors 0 0). This is because all players are all white when they first enter the game, so this will ban all players from your server!

Of course, you can also dispense "ban_color" commands from within the game.