TeamSpeak is a voice chat platform widely used by gaming communities and teams that need clear, low-latency voice. In this guide you will install the TeamSpeak 3 server on Ubuntu 24.04, run it under a dedicated system user managed by systemd, open only the ports it needs, claim server admin rights with the privilege key, and administer the server from the command line with ServerQuery. The TeamSpeak 3 client and the newer TeamSpeak clients can both connect to this server.
Prerequisites
To follow this guide you need:
- A server running Ubuntu 24.04 LTS on x86_64, for example a CubePath VPS. 1 vCPU and 1 GB of RAM are enough for a community server.
- A non-root user with
sudoprivileges. - The TeamSpeak client installed on your computer.
Without a license file, the TeamSpeak 3 server runs one virtual server with up to 32 simultaneous users, which is enough for most small communities.
Step 1 - Creating a dedicated user
The TeamSpeak server should never run as root. Create a system user with its home directory in /opt/teamspeak and no login shell:
sudo useradd --system --create-home --home-dir /opt/teamspeak --shell /usr/sbin/nologin teamspeak
Check that the user and directory exist:
id teamspeak
ls -ld /opt/teamspeak
uid=998(teamspeak) gid=998(teamspeak) groups=998(teamspeak)
drwxr-x--- 2 teamspeak teamspeak 4096 Sep 25 10:00 /opt/teamspeak
Step 2 - Downloading the server
TeamSpeak distributes the Linux server as a .tar.bz2 archive. Check the TeamSpeak downloads page for the latest 3.x version and its SHA256 checksum. At the time of writing it is 3.13.7.
Install bzip2 so tar can extract the archive, and download it to a temporary directory:
sudo apt update
sudo apt install bzip2
cd /tmp
wget https://files.teamspeak-services.com/releases/server/3.13.7/teamspeak3-server_linux_amd64-3.13.7.tar.bz2
Compare the checksum with the one on the downloads page:
sha256sum teamspeak3-server_linux_amd64-3.13.7.tar.bz2
If the two values do not match, delete the file and download it again. Extract the archive straight into /opt/teamspeak, dropping the top-level directory, and hand ownership to the teamspeak user:
sudo tar -xjf teamspeak3-server_linux_amd64-3.13.7.tar.bz2 -C /opt/teamspeak --strip-components=1
sudo chown -R teamspeak:teamspeak /opt/teamspeak
Check that the server binary and scripts are in place:
sudo ls /opt/teamspeak | grep ts3server
ts3server
ts3server_minimal_runscript.sh
ts3server_startscript.sh
Step 3 - Accepting the license
The server refuses to start until you accept the TeamSpeak license. Read it first:
sudo less /opt/teamspeak/LICENSE
If you agree with its terms, accept it by creating an empty marker file owned by the teamspeak user:
sudo -u teamspeak touch /opt/teamspeak/.ts3server_license_accepted
Step 4 - Creating a systemd service
A systemd unit starts TeamSpeak at boot, restarts it if it crashes and sends its console output to the journal. The ts3server_minimal_runscript.sh script shipped with the server sets the library path and runs the server in the foreground, which is exactly what systemd expects.
Create the unit file:
sudo nano /etc/systemd/system/teamspeak.service
[Unit]
Description=TeamSpeak 3 Server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=teamspeak
Group=teamspeak
WorkingDirectory=/opt/teamspeak
ExecStart=/opt/teamspeak/ts3server_minimal_runscript.sh
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Load the unit, then enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable --now teamspeak
sudo systemctl status teamspeak --no-pager
● teamspeak.service - TeamSpeak 3 Server
Loaded: loaded (/etc/systemd/system/teamspeak.service; enabled; preset: enabled)
Active: active (running)
Step 5 - Saving the admin credentials
On its very first start the server creates two credentials and prints them only once:
- The ServerQuery admin password for the
serveradminaccount, used for command line administration. - A privilege key (token) that grants the Server Admin group to the first client that uses it.
Because systemd captured the console output, you can read them from the journal:
sudo journalctl -u teamspeak --no-pager | grep -E 'loginname|token='
loginname= "serveradmin", password= "aB3dE5fG"
token=Xy1Zabc2DEF3ghi4JKL5mno6PQR7stu8VWX9yz0A
Store both values in a password manager now.
Confirm that the server is listening on its ports:
sudo ss -tulpn | grep ts3server
udp UNCONN 0 0 0.0.0.0:9987 0.0.0.0:* users:(("ts3server",pid=2211,fd=13))
tcp LISTEN 0 128 0.0.0.0:10011 0.0.0.0:* users:(("ts3server",pid=2211,fd=17))
tcp LISTEN 0 128 0.0.0.0:30033 0.0.0.0:* users:(("ts3server",pid=2211,fd=16))
...
These are the ports TeamSpeak uses:
| Port | Protocol | Purpose | Open to the Internet? |
|---|---|---|---|
| 9987 | UDP | Voice | Yes |
| 30033 | TCP | File transfers (avatars, channel files) | Yes |
| 10011 | TCP | ServerQuery (raw) | No |
| 10022 | TCP | ServerQuery over SSH, when enabled | No |
Step 6 - Opening the firewall
Only voice and file transfer need to be reachable by clients. Keep the ServerQuery ports closed: you will use them from the server itself, and exposing them invites password guessing. Allow SSH first so you keep access:
sudo ufw allow OpenSSH
sudo ufw allow 9987/udp
sudo ufw allow 30033/tcp
sudo ufw enable
Verify the rules:
sudo ufw status
Status: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
9987/udp ALLOW Anywhere
30033/tcp ALLOW Anywhere
...
Step 7 - Claiming admin rights from the client
Open the TeamSpeak client and connect to your_server_ip (the default port 9987 is used automatically). When you connect for the first time, the client asks for a privilege key. Paste the token from Step 5. If the prompt does not appear, use Permissions, then Use Privilege Key.
Your identity is now in the Server Admin group. From the client you can:
- Right-click the server name and choose Edit Virtual Server to set the server name, a welcome message and an optional server password.
- Right-click the server name and choose Create Channel to add channels. Set the codec to Opus Voice with a quality between 6 and 10 for good voice quality, and tick Permanent so the channel survives server restarts.
- Use Permissions, Server Groups to review what the default groups (Server Admin, Normal, Guest) are allowed to do.
The privilege key is single-use. To give admin rights to another person, create a new key as described in the next step.
Step 8 - Administering the server with ServerQuery
ServerQuery is a text protocol for scripting and automating TeamSpeak. Because you did not open its ports in the firewall, connect from the server itself. Install the telnet client:
sudo apt install telnet
Connect to the raw ServerQuery port:
telnet 127.0.0.1 10011
TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
Log in with the password from Step 5 and select the first virtual server:
login serveradmin your_serverquery_password
use sid=1
Each command answers with error id=0 msg=ok on success. A few useful commands follow. In ServerQuery, spaces inside values are written as \s.
Show the server status and the connected clients:
serverinfo
clientlist
Rename the virtual server:
serveredit virtualserver_name=My\sTeamSpeak\sServer
Create a permanent channel that uses the Opus Voice codec (channel_codec=4):
channelcreate channel_name=General channel_codec=4 channel_codec_quality=8 channel_flag_permanent=1
Create a new privilege key for the Server Admin group, which has ID 6 on a fresh server (check with servergrouplist):
privilegekeyadd tokentype=0 tokenid1=6 tokenid2=0
Close the session:
quit
To run ServerQuery from your own computer instead, tunnel the port over SSH rather than opening it in the firewall:
ssh -L 10011:127.0.0.1:10011 your_user@your_server_ip
While the tunnel is open, connect your ServerQuery tool to 127.0.0.1:10011 on your computer.
Troubleshooting
The service stops right after starting. Read the journal and the server logs:
sudo journalctl -u teamspeak -n 50 --no-pager
sudo ls /opt/teamspeak/logs/
If the log mentions the license, make sure /opt/teamspeak/.ts3server_license_accepted exists and belongs to teamspeak. Permission errors usually mean some files are still owned by root; run sudo chown -R teamspeak:teamspeak /opt/teamspeak and restart the service.
Clients cannot connect. Check that UDP 9987 is open in UFW and in any external firewall, and that the process is listening with sudo ss -ulpn | grep 9987.
You lost the privilege key or the ServerQuery password. If you still have the ServerQuery password, create a new key with privilegekeyadd as shown above. If you lost the ServerQuery password, stop the service and start the server once by hand with a new password, then stop it with Ctrl+C and start the service again:
sudo systemctl stop teamspeak
sudo -u teamspeak /opt/teamspeak/ts3server_minimal_runscript.sh serveradmin_password=your_new_password
sudo systemctl start teamspeak
"Server is full" errors. Without a license the server allows 32 simultaneous users. Larger communities need a license from TeamSpeak.
Conclusion
You now have a TeamSpeak 3 server on Ubuntu 24.04 running as an unprivileged user under systemd, with only the voice and file transfer ports exposed, admin rights claimed and ServerQuery available for automation. As next steps, back up /opt/teamspeak/ts3server.sqlitedb and the /opt/teamspeak/files directory regularly, review the server group permissions before inviting users, and follow the TeamSpeak release notes to apply server updates by replacing the binaries while the service is stopped.