Sys Admin Guide

From ioquake3 wiki
Revision as of 17:06, 7 October 2015 by TimeDoctor (talk | contribs) (So, You've Decided to Start a Dedicated Quake 3: Arena Server.)
Jump to: navigation, search

So, You've Decided to Start a Dedicated Quake 3: Arena Server.

This guide will help you get started.

If there isn’t a solution for the problem you ran into on this page, please try asking on our forums or in our live chat channel.

You will need a legitimate copy of Quake 3: Arena. It is currently only available through Steam on Windows or if you'd like it on-disc second-hand markets like Ebay may have copies.

Once you have the game downloaded, copy pak0.pk3 to your server's baseq3 directory.

Most of the information on this page also applies to any Quake 3 mods or new games that work with ioquake3.


Forward and open port 27960 on your firewall or router to the machine that will act as the dedicated ioquake3 server.


  1. Create a new user for your ioquake3 server to run as. You can use the command sudo adduser ioq3srv for example to add a new user named ioq3srv
  2. Switch to the new user su - ioq3srv
  3. Download wget
  4. Install any pre-requisites according to your distribution documentation. If you run into trouble here, please ask for help on our forums after attempting the next command and saving the output to pastebin
  5. sh
  6. Copy pak0.pk3 from your purchased copy of Quake 3: Arena to the baseq3 sub-directory of ioquake3
  7. Download wget
  8. Type screen and then sh You can leave the screen at any time by pressing Ctrl+a then d, and then get access to your running server again by typing screen -drU
  9. You're ready to go, just type map q3dm17 in your new server's console.
  10. Want to check on your server remotely without launching a full ioquake3 client or shelling in? Use qstat.

Mac OS X

  1. Install ioquake3 via the traditional dmg file.
  2. Immediately upgrade to a test build by downloading the zip file, extract the from the zip file and place it inside your /Applications/ioquake3 folder.
  3. Copy pak0.pk3 from your baseq3 folder on your Quake III: Arena CD-ROM or Steam installation to your /Applications/ioquake3/baseq3 folder.
  4. Open
  5. Type this and press enter, do the same for the next few lines: cd /Applications/ioquake3/
  6. curl -O
  7. sh
  8. Type screen and then sh You can leave the screen at any time by pressing Ctrl+a then d, and then get access to your running server again by typing screen -drU
  9. You're ready to go, just type map q3dm17 in your new server's console.


We don't have instructions for running a dedicated ioquake3 server on Windows yet! Please edit this document and help us get one together.

Configuration Files

You can put almost any setting or console command into a configuration file called suchandsuch.cfg and place this in the mod folder, for regular Quake III: Arena it is baseq3 and then modify your server startup command or script to end with +exec suchandsuch.cfg


Rcon allows you to remotely access and configure your server while playing through a client or through other programs.

seta rconPassword "password"
Adding this to your server configuration file (suchandsuch.cfg) will enable remote access through the password in quotes. Do not use password or any other simple word. Please use a password manager like 1Password to keep track of your passwords.

Useful ioquake3 server console commands and settings

g_gametype 1
Change the game mode after you change the map, 1 is deathmatch, 2 is one on one, 3 is team deathmatch, 4 is capture the flag.
bot_enable 1 or 0
Enables or disables bots on your server. 1 is on, 0 is off.
bot_minplayers <range>
Specifies a number of bots that should connect to the server when there are fewer than this number of human players. For example, if bot_minplayers is set to 2 and one human player connects and joins the game then one of the bots will disconnect and the other will keep on playing.
addbot <botname> <difficulty range> <teamcolor>
Use this command to manually add bots to a server, optionally specifying the difficulty and team. The bots names are the same as the in-game names (Sarge, etc.) The difficulty is any whole number 1 through 5. 5 is the most difficult, 1 is the least. Team color is either red or blue
g_allowvote 1 or 0
Enable or disable player voting on the map, restarting the map, kicking a player, or the g_gametype.
banaddr <range>
ban an ip address range from joining a game on this server, valid <range> is either playernum or CIDR notation address range.
exceptaddr <range>
exempt an ip address range from a ban.
bandel <range>
delete ban (either range or ban number)
exceptdel <range>
delete exception (either range or exception number)
reload the banlist from serverbans.dat
delete all bans
restart network subsystem to change latched settings
game_restart <fs_game>
Switch to another mod
kicknum <client number>
kick a client by number, same as clientkick command
kick all clients, similar to "kick all" (but kicks everyone even if someone is named "all")
kick all bots, similar to "kick allbots" (but kicks all bots even if someone is named "allbots")
tell <client num> <msg>
send message to a single client (new to server)

Using HTTP/FTP Download Support

You can enable redirected downloads on your server even if it's not an ioquake3 server. You simply need to use the 'sets' command to put the sv_dlURL cvar into your SERVERINFO string and ensure sv_allowDownloads is set to 1

sv_dlURL is the base of the URL that contains your custom .pk3 files the client will append both fs_game and the filename to the end of this value. For example, if you have sv_dlURL set to "", fs_game is "baseq3", and the client is missing "test.pk3", it will attempt to download from the URL ""

sv_allowDownload's value is now a bitmask made up of the following flags:

   1 - ENABLE
   4 - do not use UDP downloads
   8 - do not ask the client to disconnect when using HTTP/FTP

Server operators who are concerned about potential leeching from their HTTP servers from other ioquake3 servers can make use of the HTTP_REFERER that ioquake3 sets which is "ioQ3://{SERVER_IP}:{SERVER_PORT}". For, example, Apache's mod_rewrite can restrict access based on HTTP_REFERER.

Downloading via UDP has also been improved in ioquake3 and yields higher data rates. You can configure the maximum bandwidth for UDP downloads via the cvar sv_dlRate. Due to system-specific limits the download rate is capped at about 1 Mbyte/s per client, so curl downloading may still be faster.

Using Old Versions or Protocols

Sometimes we get asked to help with NoGhost or other mods that require versions of Quake 3 prior to 1.32c. Unfortunately there is no way to make mods that require old versions of Quake 3 work with ioquake3. When id software released the source code which ioquake3 is based on we only received access to the latest version at the time they stopped working on it.


Similarly, we sometimes get asked to support Punkbuster. This is closed source cheat detection software that we don't have the ability to use with ioquake3.

Network protocols

There are now two cvars that give you some degree of freedom over the reported protocol versions between clients and servers: com_protocol and com_legacyprotocol. The reason for this is that some standalone games increased the protocol number even though nothing really changed in their protocol and the ioquake3 engine is still fully compatible.

In order to harden the network protocol against UDP spoofing attacks a new network protocol was introduced that defends against such attacks. Unfortunately, this protocol will be incompatible to the original quake3 1.32c which is the latest official release from id. Luckily, ioquake3 has backwards compatibility, on the client as well as on the server. This means ioquake3 players can play on old servers just as ioquake3 servers are able to service old clients.

The cvar com_protocol denotes the protocol version for the new hardened protocol, whereas the com_legacyprotocol cvar denotes the protocol version for the legacy protocol. If the value for com_protocol and com_legacyprotocol is identical, then the legacy protocol is always used. If com_legacyprotocol is set to 0, then support for the legacy protocol is disabled.

Mods that use a standalone engine obviously do not require dual protocol support, and it is turned off if the engine is compiled with STANDALONE per default. If you desire backwards compatibility to older versions of your game you can still enable it in q_shared.h by defining LEGACY_PROTOCOL.

cl_guid Support

cl_guid is a cvar which is part of the client's USERINFO string. Its value is a 32 character string made up of [a-f] and [0-9] characters. This value is pseudo-unique for every player. id's Quake 3 Arena client also sets cl_guid, but only if Punkbuster is enabled on the client.

If cl_guidServerUniq is non-zero (the default), then this value is also pseudo-unique for each server a client connects to (based on IP:PORT of the server).

The purpose of cl_guid is to add an identifier for each player on a server. This value can be reset by the client at any time so it's not useful for blocking access. However, it can have at least two uses in a mod's game code:

  1. improve logging to allow statistical tools to index players by more than just name
  2. granting some weak admin rights to players without requiring passwords

I just want to play Quake 3

Please read the Players Guide