Sys Admin Guide

From ioquake3 wiki
Revision as of 13:50, 4 February 2018 by ZTurtleMan (talk | contribs) (Add cvars that were documented in the systemd service file at ioq3.git/misc/linux/q3a.service.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to 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 UDP 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 (make, git, gcc, etc) 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 the patch zip file from this page and unzip the contents into your baseq3 and missionpack sub-directories of ioquake3.
  8. Download wget
  9. 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
  10. You're ready to go, just type map q3dm17 in your new server's console.
  11. 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. Download the patch zip file from this page and unzip the contents into your baseq3 and missionpack sub-folders of your ioquake3 folder.
  5. Open
  6. Type this and press enter, do the same for the next few lines: cd /Applications/ioquake3/
  7. curl -O
  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.


  1. Install ioquake3 via the old installers.
  2. Immediately upgrade to a test build by downloading the zip file, extract the ioquake3 files from the zip and overwrite the ones with the same names in your \ioquake3 directory where you chose to install it in step 1.
  3. Copy pak0.pk3 from your baseq3 folder on your Quake III: Arena CD-ROM or Steam installation to your \ioquake3\baseq3 directory.
  4. Open a Command Prompt (cmd.exe).
  5. Change to your ioquake3 directory by typing cd C:\Programs (x86)\ioquake3 then press enter.
  6. Type ioq3ded.x86_64.exe +set dedicated 2 +set sv_allowDownload 1 +set sv_dlURL "" +set com_hunkmegs 64.
  7. You're ready to go, just type map q3dm17 in your new server's console.

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

These can be set on the command line using "ioq3ded.x86_64 +command" or in the console interface after starting the server.

set dedicated 2
Enabled listing server on public Internet master servers. +set dedicated 2 is public Internet, 1 is LAN/connect by IP (the default), 0 is non-dedicated (client binary only). It must be set in the command line arguments.
set fs_game <mod directory>
Set mod to play. For example to play Quake 3: Team Arena use +set fs_game missionpack. It must be set in the command line arguments or changed using game_restart <mod directory>.
map <map name>
Load a new map. Type map and press the tab key to list all maps.
devmap <map name>
Load a map with cheats enabled. Type devmap and press the tab key to list all maps.
map_restart <seconds>
Restart the map after an optional count down (default: 5 seconds).
set g_gametype 1
Change the game mode. It takes affect after you load a new map. 0 is deathmatch, 1 is one on one (tournament), 2 is single player deathmatch (not available in multiplayer), 3 is team deathmatch, 4 is capture the flag.
set sv_pure 0
sv_pure 0 allow clients to use addon pk3s not installed on the server. sv_pure 1 restricts clients to using pk3s installed on the server.
set net_port <port>
The UDP port that players connect too (default 27960). When running multiple servers it's useful to specific the port on each server (27960, 27961, etc).
set com_hunkMegs <megabytes>
Set amount of memory for Quake 3's Hunk memory (default 128). You may need to increase it to run some addons. It must be set in the command line arguments.
set bot_enable 1 or 0
Enables or disables bots on your server. 1 is on, 0 is off.
set 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
set 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_allowDownload 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 can be set to one of these options:

sv_allowDownload 1
Enable downloads
sv_allowDownload 4
disable UDP downloads
sv_allowDownload 8
do not ask the client to disconnect when using HTTP/FTP downloads

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.

Is ioquake3 network compatible with the final id point release (1.32c) of Quake III: Arena?

Yes. ioquake3 is ONLY network compatible with the final id software point release (1.32c) of Quake 3.

Using Old Versions or Protocols

The majority of mods built for Quake 3 1.32c work fine with ioquake3, but sometimes we get asked to help with NoGhost or other mods that require versions of Quake 3 prior to 1.32c. When the source code to Quake 3 was released it was for version 1.32c which is why ioquake3 increased the version number from there. We did not receive the source code for versions prior to 1.32c and there is no way for us to go back to 1.16n or other old versions. For the very few mods that require 1.16n, there is no way to make them work on ioquake3.

Does Punkbuster or other anti-cheat software work with ioquake3?

No. Punkbuster is closed-source software that we cannot implement. There is no good software replacement. Good administrators on your server who can watch out for cheaters, review logs, and review recorded demo files are the only anti-cheat option at this time.

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