TSN RANKSYSTEM

A PHP Bot that assigns time-based server groups
on your TeamSpeak server.

Download

The TSN Ranksystem is an open source project,
it is free to use under the GNU GPLv3 license.

Download the latest version:
DOWNLOAD (Version:1.3.23)
 

MD5: 5a7ac3099b5dd2c5374f7b123a9e9b32

Do you like this tool?

Then you might want to sponsor a beer for the developer.

This enables them to develop new features more smoothly! ;-)
Donate (via PayPal)

Features

The TSN Ranksystem brings two components:

1) A TeamSpeak Bot &
2) A Website with:
- a statistics page (demo) &
- a web interface (demo)


TeamSpeak Bot
The TeamSpeak bot connects to the TeamSpeak server over the official TS3 Query interface. The bot does all back-end (background) jobs. It collects the online & active time of the TS3 user, calculates all statistics and collects several other data. It is also available for chat commands. And sure, it gives the server groups to the clients (e.g. military ranks, level, prestiges).

Statistics Page
On the public statistics page are several data available. There are displayed statistics about clients and the server.
It is much as powerful to describe all. To name only a few things:
- You'll find a ranking list, to get the most active users.
- It has also a server usage graph, which shows the online clients and channel per time.
- Client statistics about: online & active time, versions, nationalities, platforms, used slots, and much more...

Web Interface
With the web interface, you can easily administrate the bot. It is an access secured site for the administrators of the Ranksystem. They can manage the bot, like start and stop them. All parameters are defined in this place to individually configure the Ranksystem for the needed of your TS3 server. Sure, it is well documented directly inside the web interface.

Voting

Result of the last voting - Feb. 2023



Installation on Linux

1) Requirements

Before you can start running the TSN Ranksystem Bot on your TeamSpeak server, we need to check the requirements of your environment.

 

For the statistics page and to be able to run the Bot in a PHP process, we need a webspace (webserver).

 PHP 5.5.0 or higher (PHP 8.2 ready!)
 PHP with privileges for the command "exec"
 PHP with unlimited script execution time; especially you should check this on a webhosting
 required PHP extensions:
- PHP PDO extension
- PHP PDO MySQL driver
- PHP cURL extension
- PHP Zip extension
- PHP OpenSSL extension
- PHP SSH2 extension
- PHP mbstring extension

 network connection to the TS3 ServerQuery of your TS3 server on TCP; default port 10011
 network connection to ts-ranksystem.com (IP: 193.70.102.252 + 145.239.130.173) on TCP port 443
 optional: job scheduler (for automatically restart the Bot) like a cronjob

The database will storage all information. This is necessary to get a real time statistic page.

 MySQL (or derivative like MariaDB)
 requires its own database
 required privileges:
- Data:
SELECT, INSERT, UPDATE, DELETE
- Structure:
CREATE, ALTER, INDEX, DROP

To connect with the TeamSpeak 3 server, we need access to the TS3 ServerQuery interface.

 Network connection between the webspace and the TS3 ServerQuery
 TS3 ServerQuery User with following permissions:
- b_virtualserver_info_view
- b_virtualserver_client_list
- b_virtualserver_client_dblist
- b_virtualserver_client_dbsearch
- b_virtualserver_client_dbinfo
- b_virtualserver_notify_register
- b_virtualserver_servergroup_list
- b_virtualserver_servergroup_client_list
- i_group_member_add_power
- i_group_member_remove_power
- b_icon_manage
- b_client_remoteaddress_view
- i_client_private_textmessage_power
- i_ft_file_browse_power
- i_ft_file_download_power

 

2) Download & Unzip

Download and unzip the file ranksystem_latest.zip.

 

3) Upload to webspace

Upload the whole unzipped folder to a directory on your webspace and grant permissions to the user of your webserver.

 

4) Run install process

Open the "install.php" on your browser and follow the instructions https://your.url/ranksystem-folder/install.php.

 

5) Configure webinterface

Configure the TSN Ranksystem about the webinterface https://your.url/ranksystem-folder/webinterface/.
For each parameter you'll find a documentation by mouse click on it.

 

6) Start Bot

Start the TSN Ranksystem Bot via the webinterface.

 

7) Add cronjob (optional)

Optional: Create a cronjob to be sure, the Bot is running 24/7. This will restart the Bot automatically, e.g. on a database restart.

Open a SSH session to the host machine of your webserver.

Enter the command crontab -e, go to editing mode (in VIM you need to press i).

Paste the following in a new line:

*/10 * * * * sudo -u www-data php /path_to_your_webspace/path_to_the_ranksystem/worker.php check >/dev/null 2>&1

Configure the path, where your TSN Ranksystem is located and replace www-data with the user of your webserver.

Save and quit the crontab (in VIM :wq).

Installation on Windows

1) Requirements

Before you can start running the TSN Ranksystem Bot on your TeamSpeak server, we need to check the requirements of your environment.

 

For the statistics page and to be able to run the Bot in a PHP process, we need a webspace (webserver).

 PHP 5.5.0 or higher (PHP 8.2 ready!)
 PHP with privileges for the command "exec"
 PHP with unlimited script execution time; especially you should check this on a webhosting
 required PHP extensions:
- PHP PDO extension
- PHP PDO MySQL driver
- PHP COM extension
- PHP cURL extension
- PHP OpenSSL extension
- PHP SSH2 extension
- PHP mbstring extension

 network connection to the TS3 ServerQuery of your TS3 server on TCP; default port 10011
 network connection to ts-ranksystem.com (IP: 193.70.102.252 + 145.239.130.173) on TCP port 443
 optional: job scheduler (for automatically restart the Bot) like a task scheduler

The database will storage all information. This is necessary to get a real time statistic page.

 MySQL (or derivative like MariaDB)
 requires its own database
 required privileges:
- Data:
SELECT, INSERT, UPDATE, DELETE
- Structure:
CREATE, ALTER, INDEX, DROP

To connect with the TeamSpeak 3 server, we need access to the TS3 ServerQuery interface.

 Network connection between the webspace and the TS3 ServerQuery
 TS3 ServerQuery User with following permissions:
- b_virtualserver_info_view
- b_virtualserver_client_list
- b_virtualserver_client_dblist
- b_virtualserver_client_dbsearch
- b_virtualserver_client_dbinfo
- b_virtualserver_notify_register
- b_virtualserver_servergroup_list
- b_virtualserver_servergroup_client_list
- i_group_member_add_power
- i_group_member_remove_power
- b_icon_manage
- b_client_remoteaddress_view
- i_client_private_textmessage_power
- i_ft_file_browse_power
- i_ft_file_download_power

 

2) Download & Unzip

Download and unzip the file ranksystem_latest.zip.

 

3) Upload to webspace

Upload the whole unzipped folder to a directory on your webspace and grant permissions to the user of your webserver.

 

4) Run install process

Open the "install.php" on your browser and follow the instructions https://your.url/ranksystem-folder/install.php.

 

5) Set PHP Path

Set the path to the php.exe (PHP installation) inside the other\phpcommand.php. Examples you'll find inside this file.

 

6) Configure webinterface

Configure the TSN Ranksystem about the webinterface https://your.url/ranksystem-folder/webinterface/.
For each parameter you'll find a documentation by mouse click on it.

 

7) Start Bot

Start the TSN Ranksystem Bot via the webinterface.

 

8) Add new Task (optional)

Optional: Create a task inside the task scheduler to be sure, the Bot is running 24/7. This will restart the Bot automatically, e.g. on a database restart.

Windows help how to create a new task.

Add the following options:

C:\path\to\php.exe -f C:\path\to\Ranksystem\worker.php check

Configure the path, where you find your PHP installation and also the path where your TSN Ranksystem is located.

Get a hosting

When you are not able to host the TSN Ranksystem yourself, you can ask here for a hosting.

The hosting is absolutely free. If you want to support this service, donations are welcome. ;-)

If we accept your request, the hosting will remain as long as the Ranksystem Bot is running and able to connect to your TS server. Bots, which are offline for two weeks (=inactive), will be deleted. The hosting ends at this point. Before you will receive additional warnings; starting with an offline time of three days.


Request a hosting

With the hosting we take the part of the requirements of the webspace and the database.
You still need:
- ServerQuery credentials   (Required is an access to the TS3 server via ServerQuery; ServerQuery credentials (username and password) are necessary!
- Opened Firewall      (Be sure your TS3 server and all between (host machine, firewall, ...) allows a connection from our IP address 193.70.102.252 + 145.239.130.173).
- TeamSpeak whitelist    (You should whitelist these IP also inside the query_ip_whitelist.txt, which you'll find inside the TS3 server installation directory.)

 
 
 

After submitting your request, you will automatically receive an email for confirmation. Please check your spam folder if you can't find it. By confirming your email address, we will send you an additional email with all necessary information (hosting credentials & guide).

Server relocation

We would like to inform you that we are migrating our services to a new hosting server. This move ensures improved performance, scalability, and long-term reliability.

Please whitelist the following IP addresses on your TeamSpeak 3 server:
141.94.30.49
193.70.102.252

To do this, add them to query_ip_whitelist.txt or query_ip_allowlist.txt in your TeamSpeak 3 server's installation folder.

If you are using a TeamSpeak hosting provider, check your hosting provider's web panel for an option to whitelist or forward this message accordingly.

Please also ensure that these IPs are allowed through your firewall or network settings.

Scheduled Migration:
Date: Monday, June 23, 2025
Time: 3:00 PM (CEST)
Expected Downtime: approx. 60 minutes

All data will be preserved. After the relocation, the bot will automatically reconnect using the new IP address.

The old IP (145.239.130.173) address can be removed after the migration.

Thank you for your cooperation!

 

Bot Commands

CommandParameterBot-AdminDescription
!help
!info
!cmd
!commands		- none -- / -Get a list of valid bot commands
Since version 1.3.0 it will sends you here.
!news- none -- / -Get the latest news for the Ranksystem from the Ranksystem news server.
!version- none -- / -Returns the current version under which the Ranksystem runs.
!update
!checkupdate		- none -requiredPerforms a check for new available updates.
Since the Ranksystem updates itself automatically, the update
process will be started as soon as a new version detected.
!next
!nextup		- none -- / -This checks the user-related required time to reach the
next higher rank. The investigated time will be sent as a private
chat message to the user.
!restart
!reboot		- none -requiredInitiates a reboot of the Ranksystem bot.
!shutdown
!quit
!stop		- none -requiredInitiates a shutdown of the Ranksystem bot.
!log
!logs		Parameter 1
number of log entries
expect number between 1 and 999

Example:
!log 5
This will give you the last 5 log lines.		requiredGet the last few log entries of the Ranksystem-Log
via private chat message.
!runtime
!runtimes		- none -- / -Get the last 10 runtimes of the Ranksystem bot.
Each value represents the needed duration for one round
of the bot, measured in seconds.
!uptime
!online		- none -- / -The bot sends the time of the last (re)start and
also calculates the online time.
!memory- none -- / -Get the needed memory the Ranksystem bot is using inside the PHP process.
PHP brings a overhead, so the PHP process on the system needs more memory.
!clean- none -requiredStarts the process of cleaning the user database.
It only takes effect when the function 'clean clients' is activated.
!reloadgroups
!reloadicons		- none -requiredCleans the group cache.
All server groups will be reloaded from the TS3 server and associated with this the group icons will be re-downloaded.
Also the server icon will be re-downloaded.
 

Changelog

Explanation

!   Note          (bigger) change you should notice of; in some cases there are things to do
*   Information   for your information, but there is nothing you need to do; changed something works in background
+   Feature       added a new feature or enhanced a feature
-   Bugfix        fixed a bug or corrected something
 
 

1.3.24 (not yet released)

beta-1 * updated polish language; thx to toster234
beta-1 * updated jQuery library to version 3.7.1
beta-1 * updated Font Awesome library to version 6.5.2
beta-1 * updated PHP smarty lib to version 5.4.5
beta-1 * improved ts3phpframework to support PHP 8.4
beta-1 - fixed missing menu button on webinterface and stats page on lower resolutions (<768px)
 

1.3.23 (2023-03-05)

* removed style 'CosmicBlue' from sources as requested by owner JimmyNail (Terrabot)
+ added new admin function "merge user"
- fixed unique Client-ID were not shown on the list rankup (/stats/list_rankup.php)
- fixed NOTICE messages inside of the Ranksystem Log by opening the list rankup (/stats/list_rankup.php)
 

1.3.22 (2023-01-31)

* updated jQuery library to version 3.6.2
* some code optimizations on the HTML frontend for better support other styles
* some code optimizations which considers pathes 
* optimized the tooltips on the statistics page (/stats/list_rankup.php)
* optimized determination of different database versions for rank positioning
* adjusted calculation on donut charts stats/top_week and stats/top_month, which now correlate with top_week and top_month (before they were calculated since ever)
+ added function to add individual styles for the statistics page (stats/) and webinterface (webinterface/); add your individual CSS file inside the "styles" directory -> read the "/styles/_README.php" first
+ added new style 'CosmicBlue'; by JimmyNail (Terrabot)
+ added new style 'Darkreader'; this style was generated by the Firefox extension darkreader.org
+ added new colums to the list rankup (/stats/list_rankup.php) -> sum online, idle & active time for last day, week & month
+ added to API to the function 'bot'; with this it is possible to start/stop the Ranksytem via URL or something like webcron
+ added the possibility to change the prefix (default "!") for bot commands as chat on the TeamSpeak server
+ added function to remove the servergroup (given by the Ranksystem), when a user is excepted from the Ranksystem (client or group exception)
+ added the possibility to change the colors for the donut charts and the area chart (server usage)
+ added News of the Ranksystem to webinterface & statistics page; there are also a seprate News as TeamSpeak message -> new bot command !news
- fixed redirect loop on 'Webinterface' login page for some rare constellations of environments (when the webserver config redirect to the 'Index.php' instead of 'index.php')
- fixed navbar selection on sub-pages (drop-down elements) on webinterface and stats page
- fixed negative statistic summary values (time of week / month), which appears in some special cases
- fixed update TeamSpeak message (notification about the update); before it didn't trigger in some cases
 

1.3.21 (2022-12-18)

* little improvements to be ready for PHP 8.2
- fixed wrong rank positioning (List Rankup) on MariaDB 10.6 or higher
- fixed wrong entity of special HTML characters under PHP 8.1 inside the Ranksystem log by displaying it on the webinterface (webinterface/bot.php)
 

1.3.20 (2022-06-17)

* added delay for adding / removing servergroup, when it runs into an TS3 server error (i.e. needed permissions are missed); to prevent spamming the Ranksystem log and the TS3 server
* added clean job for table 'user_iphash'; removes offline user from this table, which stucked in some special cases
* improved site load performance on 'Webinterface' -> 'TeamSpeak' settings on bigger databases; only load users, which were online between the last 30 days (for Bot-Admin)
* minor code optimizations, especially for PHP 8.1
* updated PHP smarty lib to version 4.1.0
- fixed wrongly shown the ServerIcon, when an user hasn't a rank group yet; concerned the 'Channelinfo Toplist' add-on
- fixed SQL error "Unknown column 'uuid' in 'where clause'" on exception mode 'reset time'
 

1.3.19 (2021-12-21)

- fixed SQL error during the update process (table: addons_config, column: value), which occurs in some environments
 

1.3.18 (2021-12-21)

! new TS3 permission 'b_virtualserver_channel_list' needed for channel tree
* updated hungarian language; thx to ExXeL
* removed installation path of the Ranksystem from udpate server check
+ added new add-on 'Channelinfo Toplist'; writes the Top 10 user to a channel description; TS3 permission 'b_channel_modify_description' needed for this add-on
+ added PHP smarty lib, which is used for the 'Channelinfo Toplist' add-on
+ added the possibility to disable the security check that the bot getting started from command line; in some environments (e.g. CPanel) this is needed
+ added a cancel option to the database export function; could be needed in case of running into trouble
+ added the timestamp of last seen in the confirmation request on admin function 'delete user'
+ added channel tree as a drop-down box in the webinterface on associated fields
- fixed SQL syntax error on add-on 'Assign Servergroups'
- fixed wrong operator comparision on change password function
- fixed SQL on webinterface saving an API key
- fixed possible XSS attack in log view & install.php
 
Show older entries

Support

Please report bugs and also feature requests preferred on GitHub.

You can also get support on our public TeamSpeak server ts-n.net.
Contact an admin there (server group: Ranksystem Staff Ranksystem - Staff). Please stay patient, when we don't react immediately. Please give us at least 10-15 minutes to response.

You want to ask for a free hosting? Have a look above to request a hosting.