TSN RANKSYSTEM

Features

TeamSpeak Bot

Statistics Page

Web Interface

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.

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.

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.

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.18 - NOT YET RELEASED

*beta-1 * updated hungarian language; thx to ExXeL
*beta-1 + 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
*beta-1 + added a cancel option to the database export function; could be needed in case of running into problems
*beta-1 - fixed SQL syntax error on add-on 'Assign Servergroups'
*beta-1 - removed installation path of the Ranksystem from udpate server check

1.3.17 (2021-01-24)

- fixed database error on assign servergroups functions on statistics page, when changing the server groups

1.3.16 (2021-01-03)

! We will relocate our servers to a new host in the middle of January 2021; Be sure to allow a network connection to our new IP addresses 193.70.102.252 + 145.239.130.173 (TCP port 443) to be able to receive future Ranksystem updates; the old IP address (164.132.201.2) will be reachable until the end of January 2021
* we added a connection test to the update server of the Ranksystem (on the startup of the Ranksystem) to warn if a connection fails
* changed MySQL connection to a none persistent connection, when it is not the Ranksystem Bot
* changed update check for the Ranksystem database; when the version is below 1.3.0 it now stops the Ranksystem with a critical error
+ added to API to the functions 'user' & 'userstats' the possibility to ask for multiple servergroup database IDs in a single request; example: 'groupid=6,9,48'
+ added new check for clients deleted from the TeamSpeak server, which are reconnecting with the same unique-client-ID and are still known by the Ranksystem; this clients will now get undo the "removed-flag"
+ added function to delete manually a user (or multiple) out of the Ranksystem database
- fixed on the List Rankup (statistics page) the buttons for the first / last page on the pagination

1.3.15 (2020-12-20)

* changed HTTPS check; the warning message that HTTP is used now appears only on the login page of the webinterface
* added check on database export, ZIP version is >= 1.2.0, which is needed to encrypt the ZIP file
- fixed problem on PHP 8.0 on new installations (Uncaught TypeError server_usage.php:8)

1.3.14 (2020-12-13)

! We added a new Wiki page for the Ranksystem API to Github
* updated jQuery library to version 3.5.1
* updated Font Awesome library to version 5.15.1
* updated bootstrap-select library to version 1.13.14
* updated flag-icon-css library to version 3.5.0
* updated Bootstrap Switch library to version 3.3.4
* updated hungarian language; thx to ExXeL
* changed the language dropdown symbol to the conutry icon
* minor code optimizations
+ added the possibility to define multiple groups to the add-on 'Assign Servergroups'
+ added a second sort level for the List Rankup (statistics page)
+ made the filesize on the new database export function dynamic
- fixed little CSS problem on the List Rankup (statistics page)
- fixed automatic reconnection, when the TS3 server connection was lost
- fixed switch button for 'Permanent Group' was not working after adding a new line on 'Rank Definition' site

1.3.13 (2020-11-22)

! PHP 8.0 is now supported (older versions like PHP 7.x and also PHP 5.6 are still supported)
! changed API user list by 'status'; old request was '&user&online' -> now use '&user&status=online' instead
* on database connection lost, we now try to restore the connection; a reconnect of the Ranksystem TS bot in this situation is no longer necessary
* reworked code for "fast hashing" mode for "hash IP addresses", since PHP 8.0 dropped the custom salt on passwort_hash function
* some code optimizations, also to get a better support for PHP 8.0
* users whose 'last seen' was more than 30 days ago will not be calculated any more (statistics like online last week/ month)
* moved PHP functions to its own file others/_functions.php
* optimized error log handling
* updated hungarian language; thx to ExXeL
* updated czech language; thx to Stetinac
* changed ZIP-handling in Ranksystem automatic update process to support PHP 8.0
* added also a message to the log, when the process of the Ranksystem bot was kill during stop / restart command
* optimized Ranksystem log view on the webinterface; especially on array dumps
+ added a database export function to the webinterface; this generates an SQL export file, which is zipped
+ added the possibility to sort the columns nation, version + platform on the statistics page (stats/list_rankup.php)
+ added parameter to the webinterface to set the 'SameSite' session attribute
+ added parameter to the webinterface to set the 'Access-Control-Allow-Origin', 'X-Content-Type-Options', 'X-Frame-Options' & 'X-XSS-Protection' header
+ added to API to the functions 'user' & 'userstats' the 'status' parameter; now you can get 'online' & 'offline' users
+ added to API to the functions 'user' & 'userstats' the 'groupid' parameter to get user by a defined servergroup database ID
- fixed problem, where user were shown in top users list (week, month & all) on statistics page, although they were excluded by server group exception; thx to Arci224 for reporting
- fixed lost filter (options) on the statistics page (stats/list_rankup.php)
- fixed add / remove time for offline users; problem with caching since version 1.3.9

1.3.12 (2020-09-21)

* changed the handling of text messages, which are sent from the Ranksystem Bot; now they will be sent to the same location as it is received (server chat, channel chat or private chat) without some sensitive things like !log or !next, which will be always send as private message
* changed also the handling of text messages, which are sent from the Ranksystem Bot; now we are trying to send the message to the connection ID of the user, if it is known; otherwise we still use the unique client-ID to send the message; this solves the problem, a user didn't receive a message, when the Ranksystem bot has the same unique client-ID like the sending user
* updated hungarian language; thx to ExXeL
* updated czech language; thx to Arci224
* updated polish language; thx to toster234
+ added function to add an imprint and privacy policy site to the stats page; thx to Nick Slowinski
+ added new option "permanent group" to the rank definition; this allows to set a flag for a server group that shouldn't be removed at the next rank increase; this could be nice for groups such as "member", which should stay as a permanent group
- fixed problem "SQL Unknown column 'count_week' in 'field list'" which comes with the client-database-ID check since the last release

1.3.11 (2020-09-07)

* on changing a TeamSpeak client-database-ID a user losts his "Top users" stats for week & month; this could especially happen, when a relocation to a new TeamSpeak server happened; now we try to update the old stats and replace its client-database-ID with the new one; if this is not possible, the weekly & monthly stats of the old client-database-ID will be reset to show a correct "Top users" list
* updated hungarian language; thx to ExXeL
+ added new columns nation, version & platform (/stats/list_rankup.php) as option to the default sorting
+ added excepted group list to the addon assign servergroups
+ added info to bot status inside the webinterface, when the autostart is deactivated
+ added the possibility to hide also the channel stats inside the server usage graph
- fixed problem "SQL unknown column 'rank' in 'field list'" on resetting user stats; field was being removed with version 1.3.8 in database, but not on this position

1.3.10 (2020-08-08)

* changed avatar download; download only 10 avatars a loop; continue within the next loop
+ added time of the last calculation to the my statistics page (/stats/my_stats.php)
+ added columns nation, version & platform as selectable option to the statistics page (/stats/list_rankup.php)
- fixed problem "1281: sql empty result set; Error due command clientdbinfo for client-database-ID XXX (permission: b_virtualserver_client_dbinfo needed)" occurs repeated in the log; now it will be tried to get the new database-ID and store this
- fixed problem "SQL commands failed: Data too long for column 'nation' with value 'UNKNOWN'"
- fixed problem "SQL commands failed: Out of range value for column 'server_ping' at row XXX"
- fixed problem "SQL commands failed: Out of range value for column 'total_connections' at row XXX"
- fixed missed download of groups when using command !reloadgroups; groups will be cached and the cache were not deleted on using the bot command

1.3.9 (2020-08-02)

* reworked core component of the bot; store/cache most values instead of reloading it from the database with every loop; this brings especially on bigger Ranksystem databases with a couple thousand of users a really big performance boost (reduces CPU load & load on the database)
* updated russian language; thx to bykidi
* updated hungarian language; thx to ExXeL
+ added to API the function 'userstats' to get more statistics about user and be able to sort for example for top user of the week
+ added 'sort', 'order' and 'limit' function to API

1.3.8 (2020-06-20)

! disabled update support for Ranksystem versions below 1.3.0
* added delay (5s) on syncing TS3 ServerGroups with the Ranksystem
* changed log output with log-level "6 - debug"; now also the concerned SQL statements are given out beside the error
* changed icon download as TS-iconid instead of servergroup-database-ID (needed for upcoming things)
* changed icon download with file extension (determined with MIME-Type) to be able to support all official supported extensions by TeamSpeak (bmp, gif, jpg, pbm, pgm, png, ppm, svg, xbm, xpm)
* optimized traffic & memory usage on query command "clientlist" (ts3phpframework)
* updated russian language; thx to bykidi
* updated czech language; thx to Stetinac
* updated polish language; thx to toster234
* updated hungarian language; thx to froland20
* updated portuguese language; thx to Pasha
* little database optimizations; especially on table user_snapshot (reduced storage size to ~half)
* added new check for duplicate client database IDs; this is important for the database optimization for table user_snapshot
+ added support for SVG icons (servergroup and servericon)
+ added to API an identification via API key; keys can be managed about the Ranskystem webinterface; usage /api/?apikey=XXXXX
+ added to API a function to get the online user
+ added check of multiple PHP versions also to the install process; to help to install the needed PHP extensions to the right PHP installation
+ added check for negative values of online time or idle time of a user (could happened about the administration function, when to much time was manually removed); this user will be set to zero, once with this update
+ several minor optimizations on the install process
- fixed problem, when boost group was removed manually from a user; in this case the Ranksystem did remove the boost-group instantly on giving a boost-group on a new situation (to the concerned user) instead of taking care of the (new) boost-duration

1.3.7 (2020-02-14)

! resorted webinterface, since we try to get a better structur, some things were also meaningful by adding the "expert mode"; 
! redesigned a few form fields inside the webinterface; for a better usability we replaced some fields with a drop-down field, where we have the selection (values) from the TeamSpeak server (e.g. client exceptions, servergroup exceptions); this is possible since we added the "easy mode" to the installation routine
* updated FontAwesome library to version 5.12.1
+ added an easy mode for fresh installations; it will display only the "TeamSpeak" site and the "Start / Stop bot" function inside the webinterface, until the bot is started for the first time; this is needed, since some (dropdown) fields will get its data from the TS server
+ added API for third party applications to get information as JSON string; the API is documentated by itself; simple open the URL and follow the instructions; available data are user (+stats), servergroups, serverstats & rank config; (we are curious what kind of ideas you have and what cool shit you will do with it :-P  on questions and also when you have notices, let it know us!)
+ added user friendly option to customize the "boost definition"
+ added "expert mode" inside the webinterface to toggle between a clearly / simply view (default) and the expert view with all functions / parameters
+ added check to prevent negative values on removing time (about the administrate function inside the webinterface); this could happen before, if a too large value was entered
+ added sorting for the servergroup selection inside the webinterface; the sort is now the same as in TeamSpeak; query and template groups are disabled
+ added function to "Select All" or "Deselect All" on multiple choice drop-down fields
- fixed empty error message due installation, when PHP-MySQL isn't installed / enabled
- fixed mistake on administrate function "remove time", when multiple users were selected; each second user got the time added instead of removed
- fixed problem with lost time (donwgrade some user), when the connection to the TeamSpeak server was lost
- fixed continuous download of "new ServerIcon"; happened in the rare case of changing the icon-date without changing the icon itself
- fixed lost check-icon on multiple drop-down boxes, with one of the last bootstrap updates

1.3.6 (2020-01-13)

! Hotfix
- fixed wrong check on reset password function (security issue)

1.3.5 (2019-12-23)

! Hotfix
- fixed problem loosing the rankup definition on saving options inside the webinteface core-site

1.3.4 (2019-12-23)

* optimized check for Bot name; added min-length of 3 characters to avoid errors due connecting virtual server
* updated hungarian language; thx to ExXeL
* little code optimization on reset password function for the webinterface
* updated Bootstrap-select library to version 1.13.9
+ added user friendly option to customize the "rank up definition"
+ added check PHP extension mbstring is loaded
+ added azerbaijan language; thx to G. FARZALIYEV
+ added new configuration parameter for the max. clients (red) line on the server usage graph on the statistics page
- fixed spelling error in russian language; thx to Alexander
- fixed "Undefined offset" on list_rankup.php, when stored servergroup of user (which is longer time offline) isn't existing anymore

1.3.3 (2019-07-26)

! new PHP extension mbstring is needed
* optimized SQL statement of building user_snapshots
+ added hungarian language; thx to ExXeL
- fixed handling user nicknames with multibyte characters and a length longer 30
- fixed PHP warning on stats/top sites, when servergroup exception is empty

1.3.2 (2019-07-01)

- fixed looping systems, when user nicknames are longer than 28 characters

1.3.1 (2019-06-30)

! new TS3 permission 'b_virtualserver_servergroup_client_list' needed for reset function
! new TS3 permission 'b_virtualserver_client_dbsearch' needed for special case cldbid has changed
* performance optimization with optimizing the SQL handling; a few statistic values will be cached inside PHP and only saved to DB, when changes have taken place
* updated jQuery library to version 3.4.1
* updated Bootstrap library to version 3.4.1
* changed Ranksystem log; added few more things to log during startup (loglevel, query-slowmode, update-channel); changed some things to be forced to log during startup, also when bot level is very low
* optimized downloading of servergrous & icons on TS3 errors (e.g. connection lost)
* minor code optimizations
* changed core rankup assigning; now check wrong server groups and remove them; if the current level is missed, correct it and add the server group
* changed navbar inside the webinterface to be more clearly and structured
+ added automatically language support; when you add a file inside the languages folder and it fullfill the name conventions, it will be added automatically; more information you will find inside the /languages/add_new_language.php
+ added check for changed client-database-ID (e.g. happens on restoring a server snapshot) for offline user; This check was still here, but only for online user; cldbid will be updated or the time of the user reset depending on specification of 'Client-database-ID reset'
+ added new function to reset the Ranksystem
+ added bot command !memory
+ added an average looptime to the !runtime command
- fixed "DateTime::__construct()" error on /stats/my_stats.php when boost function is defined with decimal numbers
- fixed "TS3 Error: 0: only available in non-blocking mode" on secured (SSH) TS Query connection
- fixed XSS vulnerability on /stats/ top users via client_nickname
- fixed online status of users; when the last user left the TS server, it stayed online on 'List Rankup' page
- fixed rarely constellation on update servergroups in bot core, when none of this groups have an icon and also no servericon is set
- fixed rarely constellation in bot core, when only user(s) without any country flag (pre-4: or without any platform or without any version) are online
- fixed wrong response on command !clean, that you wouldn't be allowed to use the command despite admin privileges