Gloom Server Admin Guide (v.2004-06-28)

This guide will contain all the information you need to run a Quake II Gloom dedicated server. It is recommended you use an alternate Quake 2 binary such as r1q2ded / dedicated.exe instead of the vanilla Q2 binaries as they are subject to numerous bugs and security flaws which will result in crashes and possible security compromises.

Quick links: [Getting Started] [Server Variables] [Server Commands] [Permissions System] [Client Admin Commands]

Getting Started

First of all you'll need to get the latest Gloom DLL. Goto ftp://ftp.planetgloom.com/files/dll/ and download the appropriate version for your operating system and extract it to your Gloom directory.

It is recommended to specify most of your settings in a file called server.cfg inside your Gloom directory. You can then start the server with the minimum amount of command line parameters. To simply run a server with all default settings and no admins, map rotation, logging, etc you can simply do

quake2 +set dedicated 1 +set game gloom +map gloom

Your server will now be running and accepting connections on port 27910. Be sure this port is open to the outside world on your firewall or router if needed!

Now create a text file called server.cfg in your gloom directory. This is where you will put any server variables (cvars) and other commands you want to happen when the server is started. Here's an example server.cfg you may want to use:

// ========================
// Gloom important settings
// ========================
set voting 255
set deathmatch 1
set public 1
set bandwidth_mode 0
set dmflags 989855760
set secure_modulate_cap 1
set logfile 0
set timelimit 45
set login 0

set maxclients 20
set maxplayers 20

set _url "www.planetgloom.com" s

set suddendeath 5
set sv_connectmessage "Q2 Gloom - www.planetgloom.com\n"

// ==============
// Admin password
// ==============
set rcon_password "secretrcon"

// ==================
// anti bot reconnect
// ==================
set reconnect_address "1.1.1.1:27910"

// ====
// Caps
// ====
set reconnect_wait 10
set xmins 5
set max_cl_maxfps 90
set min_cl_maxfps 25

// ==============
// Accounts/tking
// ==============
set bantime 3600
set autokick 1

// =================
// Download settings
// =================
set allow_download 1
set allow_download_sounds 1
set allow_download_maps 0
set allow_download_models 1
set allow_download_players 1


// ==============
// Server aliases
// ==============
alias s status
alias i serverinfo

set hostname "My Quake II Gloom Server!"

// ========
// mapcycle
// ========
set default_maps "gloom/maps.txt"

set accounts "gloom/accounts.dat"
set wordbans "gloom/wordbans.dat"
set iplogs "gloom/iplog.dat"
set ipbans "gloom/ipbans.dat"

// ==================
// Ping master server
// ==================
setmaster master.planetgloom.com

Don't forget to change the rcon_password and reconnect_address variables above! It is generally recommended NOT to have any map or gamemap commands in your server.cfg file and have it mostly as set commands to configure the server. To then start the server, you would use the following command line:

quake2 +set dedicated 1 +set game gloom +exec server.cfg +map gloom

Now look at the gloom-specific server variables below to set up your server exactly how you want.

Server Variables

Server variables take the form of the command set variable "value" (eg, set teameven "1"). Keep in mind some variables must be set before the Game DLL loads (this means in your server.cfg or anywhere before a 'map' command). The following table contains all the recognised server variables by Gloom itself.

Boolean variables may have either a 1 (enabled/on) or 0 (disabled/off) value. Integer variables may contain any whole number. String variables may contain a string of text. Float variables may contain any real number.

Variable
Value
Default
Description
teameven
boolean
1
Force even teams.
buildercap
integer
0
Limit the number of builder classes on each team. 0 for no limit.
forceteams
boolean
0
Players cannot join teams and must be assigned by an admin.
reconnect_address
string
(empty)
Enter the IP and port of the server and players will be reconnected to it after first connecting. This is a good anti-bot protection measure. Eg, set reconnect_address "1.2.3.4:27910"
max_rate
integer
25000
The maximum allowed 'rate' client variable. It is recommended you don't change this unless you have severely limited upstream as it will impact client performance.
max_cl_maxfps
integer
90
The maximum allowed 'cl_maxfps' client variable. The higher the client's FPS, the more downstream bandwidth you will be using. Unless you have limited bandwidth, it is best to not change this.
min_cl_maxfps
integer
10
The minimum allowed 'cl_maxfps' client variable. This is used to prevent some physics bugs from occurring if a client uses a very low FPS value. Recommended not to be changed.
bantime
integer
3600
Time in seconds that automatic bans placed by the DLL last for.
autokick
boolean
1
If enabled, automatically kicks players that teamkill.
tk_threshold
integer
100
The tk counter to kick at - teamkilling higher classes increases the client's tk counter by a larger value.
teambonus
integer
850
The amount of builds points each team starts with, minus map-spawned structures. It is recommended you do not change this as additional structures could contribute to reduced performance.
login
boolean
0
Require that every player log in using a user account. If set to 1, any player connecting without a user account will be kicked.
login_message
string
(empty)
Message to be displayed to players kicked when trying to play without an account if login 1 is set.
banaccountholders
boolean
0
If set, anyone automatically banned by the DLL who has a user account will have their user account disabled.
xmins
float
5.0
How many minutes before spawns are vulnerable.
strip_names
boolean
0
Strip 'color text' from names.
strip_chat
boolean
0
Strip 'color text' from chat messages.
default_maps
string
(empty)
Path to the map list. See below for more information on map rotations.
ipbans
string
(empty)
Path to the IP bans list.
iplogs
string
(empty)
Path to the IP log.
accounts
string
(empty)
Path to the user accounts database.
wordbans
string
(empty)
Path to the word filter list.
adminlog
string
(empty)
Path to the admin log.
gloomgamelog
boolean
0
If enabled, logs a machine-readable log of each game to the gloom/logs/ folder. This log contains details of every connection, kill, death, respawn, etc for every player making it ideal to generate player statistics with.
voting
integer
255
Enable or disable certain parts of the game voting system. Add up all the values of each type of vote you wish to allow and set voting to that value:
Vote to kick a player from the server
1
Vote to change map
2
Vote to change the next map
4
Vote to kick a player on the same team as you
8
Vote to mute a player
16
Vote to end the map
32
Vote to extend the time limit
64
Vote to cause Sudden Death mode
128
votetimer
integer
30
Number of seconds players have to cast their vote.
min_votes
integer
0
Minimum number of players in game before votes can be started.
maxswitches
integer
2
Amount of times a player can switch teams before being unable to switch again.
talk_threshold
integer
120
Amount of chat before a player's chat messages are not sent (flood protection). The number is an arbitrary value, higher threshold allows for more text before engaging flood protection.
nopublicchat
boolean
0
Disables public chat.
noobserverchat
boolean
0
Disables observer chat.
deathmessages
boolean
1
Show player death messages (obituaries).
reconnect_wait
integer
20
Number of seconds to wait after a map change before allowing players to join teams.
maxplayers
integer
maxclients
Maximum number of players actually playing at any time. This may not be higher than the server client limit of maxclients.
adminslots
integer
0
Reserve a number of client slots for admins. Admins must have their user string set before connecting to use an admin slot.
bandwidth_mode
integer
0
For internet use keep this set to 0. If you are playing on a low latency connection such as a LAN, increasing bandwidth_mode shows more effects like shell casing, extra gibs, etc.
teamsplashdamage
boolean
1
Control whether splash damage (eg explosive weapons) hurt teammates.
teamspawndamage
boolean
1
Control whether players can damage or destroy their own spawn points.
teamarmordamage
boolean
0
Control whether players can damage each other's armor.
teamreflectarmordamage
boolean
0
If set, damages the person who attacked a teammate's armor.
teamreflectradiusdamage
boolean
0
If set, damages the person who hurt teammates with radius weapons.
teamdamage
integer
0
Control team damage from all types of direct contact weapons. 0 turns off team damage completely, 1 enables full damage to teammates from friendly fire of 1+ frag classes. 2 enables full damage from friendly fire and does not penalise players who teamkill.
flashlight_color
integer
0
Determine the color of the human flashlight. 0 = medium yellow/white, 1 = large bright green, 2 = small blue, 3 = small red/pink, 4 = darklight, 5 = pulsating darklight.
laser_color
integer
0
Determine the color of laser tripwires. 0 = red, 1 = green, 2 = blue, 3 = yellow.
mapdebugmode
integer
0
Enables display of map events such as triggers being hit and targets firing. Each number up to the maximum of 3 displays additionally verbose information.
secure_modulate_cap
boolean
1
Securely cap client's gl_modulate and other brightness cvars by issuing a vid_restart command when a player joins for the first time.
ceiling_eggs
boolean
0
If set, turns all eggs into ceiling eggs on map load or breeder laying.
max_frags
integer
10
Maximum number of frags a player can stockpile.
hide_spawns
boolean
1
Hide display of the opposing team's spawn count.
scoring_mode
integer
0
Change how frags are accumulated. 0 = 1 kill, 1 frag, 1 = increase frags by enemy frag cost + 1, 2 = increase frags by enemy frag cost / your frag cost.
motd
string
Welcome to Gloom 1.x
First line of the motd displayed on the client's menu.
motd2
string
www.planetgloom.com
Second line of the motd displayed on the client's menu.
motd3
string
(empty)
Third line of the motd displayed on the client's menu.
gloomcaps
boolean
1
Control whether gloom caps client cvars. Useful to turn off when mapping to allow certain commands.
suddendeath
integer
0
Number of minutes of sudden death time when the map hits the timelimit.

Server Commands

Server commands are accessed through the server console and rcon by using the command sv command. Some server commands require a player id - this can be either the player number as shown by the status command or a partial/full match of their name.

Command
Description
kickobs
Kick all observers from the server.
kick id
Kick player matching id.
adminlist
List admins that are online.
addip ip time-unit reason
Add an IP ban. ip can contain a wildcard such as 62.100.24.*. time-unit is a combination of a time and unit such as '2 weeks', '3 hours', '45 mins'. The special value -1 can be used to indicate a permanent ban. reason is the ban reason that is shown when listing bans (not revealed to the player). Eg: sv addip 62.100.24.* 2 weeks newb01: tking humie base
removeip ip
Remove an IP ban that matches ip
listip
Show a list of all IP bans, who set them, expiry and reason.
invert
Swap the bases of both teams.
search subip|subname|ip|name match
Search the IP logs. You can search by IP address or player name and either a partial or exact match. subip and subname will search for substring matches, ip and name will search for exact matches. Eg: sv search subip 24.400 will find all players with 24.400 in their IP address. sv search name BaseTK will find all players with the name BaseTK.
writeip
Write the IP ban list to disk immediately.
addaccount name pass permissions
Add a user account with username name, password pass and permissions permissions. See http://www.planetgloom.com/permissions.cgi for the permissions value calculator.
delaccount name
Delete the useraccount belonging to name.
enableaccount name [newperms]
Enable the user account belonging to name and optionally modify permissions to newperms.
disableaccount name
Disable the user account belonging to name.
reloadmapcycles
Reload the map cycle data pointed to by default_maps.
showmapcycles
List the current map cycle.
addmap mapname [min] [max]
Add the map mapname to the map rotation with optionally a min minimum player limit and max maximum player limit.
removemap mapname
Remove the map mapname from the map rotation.
who
Show a list of all players connected and their IP address or user account name.
uptime
Show the server uptime and various statistics.
listghosts
Show a list of all unclaimed ghost codes.
brightness
Make the lights fullbright.
darkness1
Make the map darker.
darkness2
Map the map really dark.
darkness3
Give everyone a headache.
globalstuff command
Globally stuff command to every connected player.
centerprint message
Show message to every connected player in the center of their screen.

Map Rotations

Gloom reads the map rotation from a file pointed to by the default_maps server variable. The maps should be in a plain text file separated by a new line. The format is mapname [minplayers] [maxplayers]

Example map rotation:

refine6 0 16
abbey 8
hellround 0 12
gloom5
hazmatb 12
gloom
deserted-r1 6
mines-1
gloom3a
r1wrecked 0 12
ore1 4

Permissions System

Gloom features a very fine granulated permissions system for in-game admins. Using the calculator at http://www.planetgloom.com/permissions.cgi you can select which privileges you wish to grant a user.

To set up the permissions system, you must run a server with the accounts variable set to a valid path and add users with the sv adduser command with the permissions you want. Users can only be added with permissions from the server console or rcon. It is recommended that your rcon password not be distributed to anyone as gloom contains enough built-in admin functions to make rcon unnecessary. Anyone with rcon access has complete unrestricted control over the server as they are able to add new users with every permission possible as well as quit the server and other such things.

Once users have been added on the server, the client must authenticate themselves to gain in-game admin status. To do this, the userinfo variable 'user' must be set on the client before connecting. For example, if a user has username fred password test, the following line in the client's config would set them up to automatically admin upon connecting:

set user "fred:test" u

Alternatively a client may login after connecting using cmd login username password from the client console, however it is recommended to use the automatic method where possible.

Client Admin Commands

About
In-game admins have limited permissions as set by the server administrator. To log in as an admin, refer to the permissions system section.

Syntax
A lot of commands have optional or required parameters and sometimes you must choose from a list of options. The following syntax is used in the client admin commands table:

id - the parameter id is not optional and must be present each time.
[] - the parameter(s) in between the brackets are optional and may be omitted.
one|two|three - you must choose either one, two or three from the list.

Example: @addip ip time-unit [reason]
This means the command may be used as follows: @addip 24.26.244.55 2 days, @addip 24.26.244.55 3 weeks sum1: tking base

Example 2: @summon tele|egg|spiker|healer|depot|gasser|turret|mgturret|detector|obstacle
This means you must choose one of the items separated by the |'s, eg: @summon tele, @summon healer, @summon detector

Example 3: @search subip|subname|ip|name match
This means you must choose either subip, subname, ip or name and specify the match parameter, eg @search subip 24.46, @search name R1, @search subname noname35

Player IDs
Often you will have to supply a player id to a command. This can be obtained using the command playerlist from the console, or you can specify a partial or full name match. Eg, @kick 1, @kick SomePlayer and @kick SomeP are all valid ways of supplying a player id.

Client Admin Command List
These commands may be entered at the client console after you have logged in:

Command
Description
Requires
@kick id
Kick player id from the server.
KICK
@ban id [time-unitreason]]
[
Ban player id. If time-unit is not specified, the default is used. A wildcard match on the last octet of the IP address the player is using is the actual IP added to the banlist.
BAN
@addip ip time-unit [reason]
Add ip to the IP ban list for time-unit with reason reason. time-unit consists of a number and unit, eg '2 weeks', '3 hours', '5 mins' or the special value -1 which indicates no expiry.
BAN
@removeip ip
Removes ip from the ban list.
BAN
@mute id
Mute player id. This prevents talking and voting.
MUTE
@unmute id
Allow muted player id to talk and vote again.
MUTE
@stuff id command
Stuff command to player id. The player is notified if you use this command.
STUFF
@summon item
Spawn an entity at your current location. item may be one of tele|egg|spiker|healer|depot|gasser|turret|mgturret|detector|obstacle. Build points are not taken not refunded.
SUMMON
@listip
Show the IP banlist. \
BAN
@map mapname
Changes the map immediately to mapname.
MAP
@check id var
Returns the value of var set by player id. Eg @check haker gl_modulate.
CHECK
@globalcheck var
Returns the value of var set by everyone on the server. May cause overflows if a lot of players are connected.
CHECK
@who
View connected players with IP or user account used to connect.
VIEW
@push [force] [radius]
Create a pushing effect centering from your position. Used to push people who are stuck back to freedom. I would not recommend going over 1000 force and 500 radius.
PUSH
@blast
Destroy whatever entity is in front of you with a rail blast. Used to destroy bad eggs etc.
BLAST
@goto id
Go to the position of player id.

@viewteamchat
View team chat (only from observer mode).
VIEWGAME
@sd
Cause Sudden Death mode immediately.
SD
@n00k1
Cause a powerful explosion centered on you.
BLAST
@n00k2
Cause a really powerful explosion centered on you.
BLAST
@setteam id team
Set player id onto team team. team may be one of human|alien|obs.
SETTEAM
@ip id
View player id's IP address.
VIEW
@classban id class
Ban player id from spawning class class. Use @classban by itself to get a list of class numbers.
CLASSBAN
@test [pvs|phs|diff] [show]
Display entities in the current PVS, PHS or the difference between the two. If show is non-zero, lines are drawn to each ent in the set. Useful for mappers to determine if too many entities are in an area.
DEBUG
@search subip|subname|ip|name match
Search the IP logs. You can search by IP address or player name and either a partial or exact match. subip and subname will search for substring matches, ip and name will search for exact matches. Eg: @search subip 24.400 will find all players with 24.400 in their IP address. @search name BaseTK will find all players with the name BaseTK. VIEW
@evadelist
Compare currently connected players with nearby bans listed in the ban list.
VIEW
@addword word
Add word to the word filter list.
WORDFILTERS
@removeword word
Remove word from the word filter list.
WORDFILTERS
@shot id
Take a screenshot of player id and yourself.
SHOT
@trace classname
Spawn an entity of classname classname on your cursor. After positioning it, use @trace again by itself to drop it and show .ent file compatible display of entity information.
DEBUG
@addaccount name pass
Add a user account with username name and password pass.
ACCOUNTS
@delaccount name
Delete user account belonging to name.
ACCOUNTS
@enableaccount name
Enable user account belonging to name.
ACCOUNTS
@disableaccount name
Disable user account belonging to name.
ACCOUNTS
@adminmode
Enter admin mode. In admin mode you can hold onto entities such as players by aiming at them and holding +attack. You can then move around to reposition them. Release +attack to drop the entity. Use @adminmode again to exit admin mode.
ADMINMODE
@viewchangelog
View a log of players who have recently used the changeclass or changeteam command.
VIEWGAME
@pause
Pause the game. Use again to resume. (buggy)
PAUSE
@light style
Create a flashlight with style specified as a number used by flashlight_color above.
TOYS
@fireworks
Create a bunch of fireworks at your current location.
TOYS