How to Set Up a Teeworlds Server on Ubuntu 26.04, Debian 13 or AlmaLinux 9
Run a Teeworlds 0.7.5 dedicated server as a systemd service on Ubuntu 26.04 LTS, Debian 13 or AlmaLinux 9 / Rocky Linux 9, with a working config and firewall rule.
Teeworlds is a free, open-source 2D multiplayer shooter, and its dedicated server is a single small binary that runs comfortably on the smallest VPS. This guide gives you a public Teeworlds server that starts at boot under systemd, on Ubuntu 26.04 LTS or Debian 13 using the distribution package, or on AlmaLinux 9 / Rocky Linux 9 using the official release archive. Ubuntu 24.04 LTS and Debian 12 use the same package and the same steps.
The current upstream release is 0.7.5, published on 19 April 2020. The project's repository is not archived and still receives occasional fixes, but there has been no newer release, so every source below installs 0.7.5. Players need a 0.7 client to join.
Requirements
- A server running Ubuntu 26.04 LTS, Debian 13, AlmaLinux 9 or Rocky Linux 9, with a user that can run
sudo. - A public IPv4 address (the examples use
203.0.113.10). - UDP port 8303 reachable from the internet. That is the server's default port.
Install on Ubuntu or Debian
Both distributions package the server as teeworlds-server (in Ubuntu it lives in the universe component). The package build includes a security patch that was added after the upstream 0.7.5 archive was published, so prefer it over the tarball on these systems.
sudo apt update
sudo apt install teeworlds-server gawk
The package installs the binary as /usr/games/teeworlds-server, a configuration file at /etc/teeworlds/server.cfg and a systemd unit named teeworlds-server.service. The unit pipes the server output through a small gawk script to add timestamps, which is why gawk is installed explicitly here.
The unit runs the server as a user called _teeworlds, which the package does not create. Create it as a system account with its own home directory:
sudo useradd --system --user-group --create-home --home-dir /var/lib/teeworlds --shell /usr/sbin/nologin _teeworlds
Write the server configuration
A Teeworlds configuration file is plain text with one setting value pair per line. The packaged example still contains a few setting names from the 0.6 series, so replace it with a file that uses the 0.7 names:
sudo nano /etc/teeworlds/server.cfg
sv_name My Teeworlds Server
sv_port 8303
sv_register 1
sv_max_clients 12
sv_player_slots 8
sv_max_clients_per_ip 2
sv_gametype ctf
sv_map ctf1
sv_scorelimit 500
sv_timelimit 20
sv_warmup 10
sv_motd Welcome. Play fair.
sv_rcon_password change-this-to-a-long-random-string
sv_rcon_max_tries 3
sv_rcon_bantime 60
What the less obvious lines do:
sv_register 1announces the server to the master servers so it appears in the in-game browser. Set it to0for a private server and add apasswordline to require a join password.sv_max_clientsis the total number of connections;sv_player_slotsis how many of them may play. The rest are spectator slots.sv_gametypeacceptsdm,tdm,ctf,lmsandlts. The map must suit the game type; the bundled maps are in/usr/share/games/teeworlds/data/maps.sv_rcon_passwordenables the remote console. If you leave it out, remote administration is disabled.
The file now contains a password, so restrict it to root and the service account:
sudo chown root:_teeworlds /etc/teeworlds/server.cfg
sudo chmod 640 /etc/teeworlds/server.cfg
The full list of settings is in the official server settings reference.
Open the firewall and start the service
Teeworlds uses UDP only. With UFW:
sudo ufw allow 8303/udp
If your provider has a separate network firewall in its control panel, allow UDP 8303 there as well. Then enable and start the server:
sudo systemctl enable --now teeworlds-server
systemctl status teeworlds-server
Install on AlmaLinux 9 or Rocky Linux 9
CentOS 6, 7 and 8 are end-of-life; AlmaLinux 9 and Rocky Linux 9 are the usual replacements. Use the official 64-bit Linux archive from the project's downloads page, which contains the server binary teeworlds_srv and the game data.
sudo useradd --system --user-group --create-home --home-dir /var/lib/teeworlds --shell /sbin/nologin teeworlds
sudo mkdir -p /opt/teeworlds
curl -LO https://github.com/teeworlds/teeworlds/releases/download/0.7.5/teeworlds-0.7.5-linux_x86_64.tar.gz
sudo tar -xzf teeworlds-0.7.5-linux_x86_64.tar.gz -C /opt/teeworlds --strip-components=1
Save the configuration shown above as /opt/teeworlds/server.cfg, then protect it:
sudo chown root:teeworlds /opt/teeworlds/server.cfg
sudo chmod 640 /opt/teeworlds/server.cfg
The official way to start the server is teeworlds_srv -f serverconfig.cfg from the game directory. Wrap that in a unit file so it survives reboots:
sudo nano /etc/systemd/system/teeworlds.service
[Unit]
Description=Teeworlds server
After=network-online.target
Wants=network-online.target
[Service]
User=teeworlds
WorkingDirectory=/opt/teeworlds
ExecStart=/opt/teeworlds/teeworlds_srv -f server.cfg
Restart=on-failure
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
Open the port in firewalld and start the service:
sudo firewall-cmd --permanent --add-port=8303/udp
sudo firewall-cmd --reload
sudo systemctl daemon-reload
sudo systemctl enable --now teeworlds
Verify that the server is reachable
Check that the process is listening on UDP 8303 and read its log:
sudo ss -ulnp | grep 8303
sudo journalctl -u teeworlds-server -n 30
On AlmaLinux or Rocky Linux the unit name is teeworlds. Then start a Teeworlds 0.7 client, open the console with F1 and connect directly:
connect 203.0.113.10:8303
If sv_register is 1, the server should also show up in the internet tab of the server browser after a short while.
Administer the server
In the client, press F2 to open the remote console and enter the value of sv_rcon_password. From there you can run server commands without restarting anything:
statuslists connected players with their IDs.kick 3removes the player with ID 3;ban 3 30bans that player for 30 minutes.change_map ctf2switches the map;restartrestarts the round.sayandbroadcastsend messages to everyone.
Settings changed through the remote console last until the next restart. To make a change permanent, edit the configuration file and restart the service:
sudo systemctl restart teeworlds-server
Troubleshooting
- The service exits immediately on Ubuntu or Debian. Confirm that the
_teeworldsuser exists, thatgawkis installed and that the account can read/etc/teeworlds/server.cfg. - Clients time out. The port is UDP, not TCP. Check both the host firewall and any provider-side firewall.
- The server is not in the browser. Look for master-server registration messages in the journal; registration fails when UDP 8303 is not reachable from outside. If the public port differs from the local one because of NAT, set
sv_external_port. - Unknown command lines in the log. A setting name from the 0.6 series is in your file; compare it with the settings reference.
Frequently asked questions
Can 0.6 clients join a 0.7 server?
No. The 0.6 and 0.7 series use different network protocols, so a 0.7.5 server only accepts 0.7 clients. Tell your players which version to install.
How do I run several servers on one VPS?
Give each instance its own configuration file with a different sv_port (8304, 8305 and so on), create one systemd unit per instance pointing at its file, and open each UDP port in the firewall.
How do I add a map rotation?
Set sv_maprotation to a space-separated list of map names and sv_matches_per_map to the number of matches played before the server moves to the next map. All maps in the list must fit the configured game type.
Do I still need screen or tmux?
No. Older tutorials start the server inside screen so that it survives an SSH disconnect. A systemd service does that job, restarts the server if it crashes and starts it at boot.