This program was tested on Windows and Linux (even without X server).
On Mac OS X 10.7.3+, Solaris and FreeBSD it should run too, but it was not tested.
All you need is a Java SE runtime environment version 8 or newer. Version 8 is recommended.
You can get the latest official versions for Windows, Mac OS X, Linux and Solaris from www.java.com/en/download/manual.jsp
FreeBSD Users should look at www.freebsd.org/java/ to learn more about Java on FreeBSD.

Linux users should install the Java package from the operating system,
so you get security updates using your package management software very easy.
To install it very easy, just use the jts3servermod_startscript.sh as root with the java argument.
Before you can use this script the first time, you have to go into the directory of the JTS3ServerMod
and allow this script being executed:
chmod +x jts3servermod_startscript.sh
After you did this, just do:
./jts3servermod_startscript.sh java
This will check, if java is already installed, and if not, it can do this for you.
If the automatic installation is not working:
An example on Debian or Ubuntu: apt-get install openjdk-8-jre-headless
An example on CentOS or Fedora -21: yum install java-1.8.0-openjdk-headless
An example on Fedora 22+: dnf install java-1.8.0-openjdk-headless
An example on OpenSUSE: zypper install java-1_8_0-openjdk-headless
Depends on the used distribution version, the OpenJDK version from the examples does not exist.
The package gcj-jre (GNU Java) will not work! Never use preview or alpha versions of Java.

Maybe you want to limit the maximum heap memory that Java use. This can be useful on a virtual server.
You can do this by using java command line arguments for the java virtual machine.
If you want to use 30 MB ram as maximum, you can start the bot like this:
java -mx30M -jar JTS3ServerMod.jar
Notice: If you choose a to low value, the bot may not run or is not stable. Useful values are between 30M and 50M.
I did no long time tests on this. The bot needs less ram if you disable the client database cache and using only one bot instance.

Teamspeak 3 server 3.0 or newer is needed, but I recommend always to use the newest version.
And of course a possible connection to the Teamspeak 3 server.

Make sure, that the IP address of the bot is white listed using the query_ip_whitelist.txt file of the Teamspeak 3 server.
For more information check out the topic "How to prevent a flood ban on the TS3 server?".

If the bot gets banned after connecting to the TS3 server, check the log file of the bot.
If you see the following line in the log file (the number might be different), the solution should work:
de.stefan1200.jts3serverquery.TS3ServerQueryException: ServerQuery Error 3331: flood ban

Solution:
You should add the IP address of the machine running this bot to the Teamspeak 3 server query_ip_whitelist.txt,
or the anti spam feature of the Teamspeak 3 server will ban this program very often for some minutes.
If the bot runs on the same machine as the TS3 server, you can set 127.0.0.1 in the bot config as address of the TS3 server.
Because 127.0.0.1 is white listed by default.

But if you are unable to change the query_ip_whitelist.txt, try to set the bot_slowmode to 1
in the bot server config file. This slows down the bot connection speed and disables some features.

Just fully unpack this ZIP file, keep the directories as they are at the ZIP file.
It is not necessary to put this bot into the same directory as the Teamspeak 3 server,
this bot is a standalone program which just connect to the Teamspeak 3 server telnet query port.

By default the Hosting Edition is using a MySQL server, open the config file config/JTS3ServerMod_InstanceManager.cfg to configure it.
Everything is explained there. But make sure that you save the config file in ANSI format (encoding ISO-8859-1) and not unicode.
All other settings will be done in the MySQL database, you can use the included PHP web interface for this.
For more information about the web interface and how to install it, please look into the webinterface/readme_webinterface.txt file.

Since this is a command line tool, it needs a shell to display messages on it.
Of course it runs also without an active shell window, simple open the logfile to get informations.

On Windows you can just open the cmd.exe or use the provided EXE files.
Linux users can run this tool even without X-Server, no GUI will be opened.
If you want to use an X-Server, just start this tool within a Terminal / Shell.
Mac OS X users should open the Terminal too.

If you put the JTS3ServerMod.jar and the config directory (containing the file JTS3ServerMod_InstanceManager.cfg)
in the same directory, you can simply start the server mod by enter
java -jar JTS3ServerMod.jar

On virtual servers you should limit the needed RAM of Java.
More information at the topic System requirements, recommended is the following value:
java -mx30M -jar JTS3ServerMod.jar

If you want to save the JTS3ServerMod_InstanceManager.cfg and JTS3ServerMod_InstanceManager.log at
a different location or just with a different name, you can use the -config and -log argument, like this:
java -jar JTS3ServerMod.jar -config cfg/instance.cfg -log log/instance.log

Another argument is -help, which only displays a list of command line arguments and quits.

It is possible to set an app.home environment variable by adding the argument -Dapp.home=PATH_TO_JTS3ServerMod
while starting the JTS3ServerMod. This way you can use the variable %apphome% at the configfile and logfile path,
which will be replaced by the app.home path. If no app.home environment variable exists,
the variable %apphome% will be replaced with an empty string.

Examples:
java -Dapp.home="D:\My Services\JTS3ServerMod\" -jar JTS3ServerMod.jar
java -mx30M -Dapp.home="/home/username/my services/JTS3ServerMod/" -jar JTS3ServerMod.jar

If you use the serveradmin query account, all permissions are already set.
Self-created query accounts might need additional permissions, even if they are in the Server Admin group.

Make sure that the following permissions are granted for the query account of the bot (in brackets why this permission is needed):
b_channel_delete_flag_force (Bad Channel Name Check)
b_channel_delete_permanent (Bad Channel Name Check)
b_channel_delete_semi_permanent (Bad Channel Name Check)
b_channel_delete_temporary (Bad Channel Name Check)
b_channel_join_ignore_password (Allow joining all channels)
b_channel_join_permanent (Allow joining all channels)
b_channel_join_semi_permanent (Allow joining all channels)
b_channel_join_temporary (Allow joining all channels)
b_channel_modify_name (Bad Channel Name Check)
b_client_channel_textmessage_send (Advertising)
b_client_delete_dbproperties (Inactive Clients Cleaner)
b_client_ignore_sticky (If you work with sticky groups)
b_client_info_view (Always needed)
b_client_remoteaddress_view (To display the IP address)
b_client_server_textmessage_send (Advertising)
b_group_is_permanent (The bot stay at this group after reconnecting)
b_virtualserver_channel_list (Always needed)
b_virtualserver_channelgroup_client_list (chat command !removechannelgroups)
b_virtualserver_client_dbinfo (Some chat commands)
b_virtualserver_client_dblist (Always needed)
b_virtualserver_client_dbsearch (Some chat commands)
b_virtualserver_client_list (Always needed)
b_virtualserver_info_view (Always needed)
b_virtualserver_notify_register (Always needed)
b_virtualserver_notify_unregister (Always needed)
b_virtualserver_servergroup_list (Always needed)
i_channel_join_power (Allow joining all channels)
i_channel_modify_power (Bad Channel Name Check)
i_channel_subscribe_power (To see clients in channels)
i_client_complain_power (Many functions if complain is enabled)
i_client_kick_from_channel_power (Bad Channel Name Check)
i_client_kick_from_server_power (Many functions)
i_client_move_power (Many functions)
i_client_permission_modify_power (Server Group Protection)
i_client_poke_power (Many functions if poke is chosen as message mode)
i_client_private_textmessage_power (Always needed)
i_group_member_add_power (Server Group Protection and Idle Check)
i_group_member_remove_power (Server Group Protection and Idle Check)

The "Guest Server Query" group also needs:
b_serverquery_login (To connect)
b_virtualserver_select (To connect)

Additional optional permission, grant it for the query account of the bot or the "Guest Server Query" group.
If set to the "Guest Server Query" group, it applies to all virtual TS3 servers:
b_serverinstance_permission_list (Displaying missing permission names in log)

You can choose different message types for the most functions of the bot,
the web interface will display an option where this is possible.
Currently there are chat and poke valid, at some functions you can also use none to disable sending a message.
Depends on Teamspeak 3 server limits, you can only use 100 characters for a poke message,
including spaces and BBCode. Chat messages have a much higher limit at 1023 characters,
also including spaces and BBCode. You should pay attention to this limits, or the bot can't send
any message and you will find an error in the logfile of the bot.

If a message will be send as kick reason, the maximum character count for the kick reason is 80.

Check first if you already have installed Java.
You can check this by writing the following command at the Console / Terminal / Command Prompt:
java -version
You should get the output of the Java version. If not, you must install Java first.
For more informations related to this check the section System requirements in this readme file.

After you did this, just fully unpack the ZIP file, where you found this file.
It is not necessary to put this bot into the same directory as the Teamspeak 3 server,
this bot is a standalone program which just connect to the Teamspeak 3 server telnet query port.
In the directory config you will find the configuration file of the JTS3ServerMod, which must be changed to fit your needs.

By default the Hosting Edition is using a MySQL server, open the config file config/JTS3ServerMod_InstanceManager.cfg to configure it.
Everything is explained there. But make sure that you save the config file in ANSI format (encoding ISO-8859-1) and not unicode.
All other settings will be done in the MySQL database, you can use the included PHP web interface for this.
For more information about the web interface and how to install it, please look into the webinterface/readme_webinterface.txt file.

Most settings will be done with the web interface, but be careful with the following functions, because wrong configuration can make big problems:
BadNicknameCheck
BadChannelNameCheck
InactiveChannelCheck
ServerGroupProtection

If one or more persons should be bot admins, you must set one of the following settings:
Bot Full Admin (all admin commands, only persons you trust!): JTS3ServerMod_InstanceManager.cfg -> bot_fulladmin_list
Bot Admin (only admin commands of the virtual bot instance): Bot Settings on the web interface

To start the JTS3ServerMod read the according section:
Run bot on Linux
Run bot on Windows

First way is to start the bot as normal application on Windows.
To do this just run JTS3ServerMod-Windows_NoWindow.exe.
All outputs of the bot will be saved to the log file, which will be created by the bot.
Of course you can put a shortcut of the JTS3ServerMod-Windows_NoWindow.exe to the Windows Auto Start directory,
to start the bot on Windows login, but make sure that the "Start in" directory is the JTS3ServerMod directory.
To open the Windows Auto Start directory, just press the two keys Windows + R and enter: shell:startup

If wanted, you can run the bot as a Windows Service, this allows the bot to run in background without a logged in user.

To create a Windows service with the Apache procrun tool, I prepared a small script which do anything for you.
In the tools sub directory you find the script InstallWindowsService.cmd and InstallWindowsService_amd64.cmd.
If you want, you can edit this script to change the config and logfile path or to change the name of the service.
But it should also work without changing anything, the default service name is JTS3ServerMod.
Just run this script with Administrator permissions (right click on it and start as an administrator).
Important: Only use the InstallWindowsService.cmd if you have the 32 bit version of the Java Runtime or
use the InstallWindowsService_amd64.cmd only if you have the 64 bit version of the Java Runtime.
If you used the wrong file, the service will not start the JTS3ServerMod. When this happen, just remove the
installed service with the RemoveWindowsService.cmd or RemoveWindowsService _amd64.cmd and install the right version.

The last step is to start the service like displayed at the end of this script.

Important:
The service needs the absolute path to all config files. But my script sends the current path to the JTS3ServerMod.
This allows to use the variable %apphome% at the path in all config files.
If the path is not available (maybe the JTS3ServerMod was not started using the service),
%apphome% will be replaced with an empty string.

The first time start the bot like described at the topic "General Informations about Installation and Usage".
As soon as everything is running like you want, stop the bot (e.g. using Ctrl + C) and go on with this topic.

The best way is to use the included jts3servermod_startscript.sh script.
Just go into the directory of the JTS3ServerMod and allow this script being executed:
chmod +x jts3servermod_startscript.sh
After that you can start the JTS3ServerMod by using:
./jts3servermod_startscript.sh start

To stop the JTS3ServerMod just do:
./jts3servermod_startscript.sh stop

Further arguments of the script are: restart, status and java

If you run into problems, check the section System requirements in this readme file.
It is possible to reduce the amount of the heap memory which java use.
This is important on Linux VServers.
If the script should do that for you, just open the file jts3servermod_startscript.sh with a text editor you like,
go to line 6 and change
JAVA_COMMANDLINE_PARAMETERS=""
to
JAVA_COMMANDLINE_PARAMETERS="-mx30M"

Also make sure that your system don't run into the open files limit if you have very much bots running at the same time.
Check the open files value using the following command: ulimit -a
You need around two files for each virtual bot instance. Example: 200 bots need at least an 400 open files limit.
Using the following command you can change that limit: ulimit -n <new limit>
Changing this value has an effect to all processes on your system!
Sometimes this setting reset to the default value. Please check how you can make the new value permanent.

On the Teamspeak 3 server you can use bot commands in the chat.
You can use the server, channel or private chat. Of course you have to be in the same channel for the channel chat.
Too many commands exists to list them here. Just do in Teamspeak server, channel or private chat: !bothelp
This displays a list of all commands. To check if the bot is running, you can also type: !botinfo
There is also a list of all bot commands in ChatCommandHelp.html.

Currently there are three different bot admins possible.
You can set full admins in the JTS3ServerMod_InstanceManager.cfg file at bot_fulladmin_list,
normal and light bot admins are set in each virtual bot instance config file for every server
at bot_admin_list and bot_lightadmingroup_list.
Full bot admins can use all bot commands on every bot instance, only add persons you trust!
Normal bot admins are limited to the own bot instance and cannot use the following commands:
!exec, !execwait, !botquit, !botinstancelist, !botinstancestart, !botinstancestop
In addition the light bot admin can't use bot commands like !botreload, !botcfgset or !botcfgget.

By default the bot will be invisible on the Teamspeak 3 server, because it is just a telnet client
and not a real Teamspeak 3 client. With default permission settings it is easy to make the bot visible
for Teamspeak 3 server administrators. Just open the Teamspeak 3 client Bookmarks -> Manage Bookmarks ->
select the server entry and click on More, if not already. Now activate the option "Show ServerQuery clients".
Now you should be able to see the bot in the Teamspeak 3 client. If still not,
check the permissions like I wrote in the next paragraph.

If you also want to allow other server groups to see the bot,
just add the permission i_client_serverquery_view_power to that group.
Use a higher value than the i_client_needed_serverquery_view_power of the bot.
But every client still need the setting in the options to see the bot.

This program creates a logfile with the name JTS3ServerMod_InstanceManager.log.
But this program will also run and work, if it cannot write or create this log file.
The logfile of the InstanceManager contains informations and errors about starting and stopping virtual bot instances.

Each virtual bot instance can create an own log file, this can be set in JTS3ServerMod_InstanceManager.cfg for every virtual bot instance.
By default the log file is named JTS3ServerMod_server1.log for the first virtual bot instance.
A virtual bot instance logs all actions on Teamspeak server and of course all errors while doing this.

The author of this program is not responsible for any damage or data loss!
It is not allowed to sell this program for money!
The modification of the file content of all included files of the JTS3ServerMod, including this manual, are not allowed!
Decompiling is not allowed! Using parts of the source code in other programs is also not allowed!
The private and commercial use of the JTS3ServerMod without paying any fees is allowed.
The author of the JTS3ServerMod don't provide any support anymore!

Teamspeak 3 is developed by TeamSpeak Systems GmbH, Sales & Licensing by Triton CI & Associates, Inc.
More information about Teamspeak 3: https://www.teamspeak.com

Launch4j was used to create the Windows executables of the JTS3ServerMod. Launch4j use the BSD/MIT license.
More information about Launch4j: http://launch4j.sourceforge.net

procrun can be used to install the JTS3ServerMod as a Windows service. procrun is an Apache Commons product and use the Apache license.
More information about procrun: https://commons.apache.org/proper/commons-daemon/procrun.html

Jsch library is used to open a connection to the encrypted SSH query of the TS3 server 3.3.0 or newer.
Jsch is an JCraft,Inc. product and use a BSD-style license.
More information about Jsch: https://github.com/mwiede/jsch

The author of the JTS3ServerMod don't provide any support anymore! E-Mails requesting technical support will not be answered.
If you run into troubles setting up the web server, you should ask in a forum with web server experts.
If you run into troubles setting up a Java runtime environment or general starting of Java applications (no JTS3ServerMod log files will be created),
you should ask in a forum for your operating system or with Java runtime experts.
For all other problems ask in the Teamspeak or TeaSpeak forums (deepens on which product you use).

If you need more information how to setup the bot correctly, please make sure that you read this file completely.
More information about the bot config files are written down in the ConfigHelp.html file.
Make sure that you read that too.

If enabled in bot configuration, you can use the following global variables for all messages:
%SERVER_NAME% - Server name
%SERVER_PLATFORM% - Server platform (Windows, Linux, ...)
%SERVER_VERSION% - Server version
%SERVER_CREATED_DATE% - Server created date
%SERVER_UPTIME% - Server uptime in days, hours, ...
%SERVER_UPTIME_DATE% - Server uptime as date
%SERVER_UPLOAD_QUOTA% - Server upload quota
%SERVER_DOWNLOAD_QUOTA% - Server download quota
%SERVER_MONTH_BYTES_UPLOADED% - Uploaded data in current month (filetransfer and avatar)
%SERVER_MONTH_BYTES_DOWNLOADED% - Downloaded data in current month (filetransfer and avatar)
%SERVER_TOTAL_BYTES_UPLOADED% - Uploaded data all times (filetransfer and avatar)
%SERVER_TOTAL_BYTES_DOWNLOADED% - Downloaded data all times (filetransfer and avatar)
%SERVER_MAX_CLIENTS% - Server max clients (slots)
%SERVER_RESERVED_SLOTS% - Server reserved slots
%SERVER_CHANNEL_COUNT% - Current channel count
%SERVER_CLIENT_COUNT% - Current client count
%SERVER_CLIENT_DB_COUNT% - Full client count of the TS3 database
%SERVER_CLIENT_CONNECTIONS_COUNT% - Server client connections count
Most server information are not updated instantly, they will be updated every 60 seconds.
If you don't need this variables, disable the global message variables in your bot configuration to save performance!

The easiest way to get the Channel ID, Client Unique ID and Client Database ID is
to install a very nice extended info pane template of dante696:
Extended Client Info on forum.teamspeak.com

If you don't want to install it, you can use the bot to get the Channel ID.
Just get the bot running and use the chat command !getchannelid <part of the Channel Name> to get the Channel ID.
As an example: !getchannelid away
If you don't change the default value -1 of bot_channel_id you don't have to know any Channel IDs on first bot start!
But make sure that you are a bot admin or full admin, or you can't use the command.

To copy the Client Unique ID of a client just open the Permissions window of your TS3 client and search for the client
you need within the server groups and make a right click on it. Now you see the context menu entry Copy UniqueID to clipboard.
Just click it and paste it where you need it.
On smaller TS3 servers you can also use the menu entry Permissions -> List All Clients, also here you can copy it
with a right click on the client. But with more than 100 clients on that TS3 server this it not really usable.

The Server Group ID and Channel Group ID will be displayed in the Permissions window after clicking on the TS3 Client menu entry
Permissions -> Server Groups
Permissions -> Channel Groups
Next to the group name you see the ID of the group. Of course you have to be connected to the server.

A small problem is the Client Database ID, because TS Systems removed almost all ways to get it using the TS3 Client.
Currently it is only possible with the optional extended info pane template.
But since JTS3ServerMod 5.3 you can use the Client Unique ID for the chat commands too.
The bot recognize automatically if you use the Client Unique ID and request the Client Database ID from the TS3 Server.

If you host the TS3 server on your own, the easiest way is to use the serveradmin login credentials of the TS3 server.
This already has almost all needed permissions and you don't have any problems with the identity of the bot.

If you don't host the TS3 server on your own or don't like to use the serveradmin account,
you can create new query login credentials with your TS3 client, you just need the permission: b_client_create_modify_serverquery_login
But first create a new TS3 identity for the bot. If you don't do this,
the bot is connected with your identity, which confuse all TS3 clients.

To create a new identity, click on Settings -> Identities -> Add
Enter a name for the identity, something like TS3 bot or JTS3ServerMod. Copy the new Unique ID and close that window.
Now connect to your TS3 server with your TS3 client using this new identity.
Click on More if the identity setting is not visible at the Connect window.
After you did this, connect again as Server Admin, if not already, and open the Permissions -> Server Groups window.
Choose the Server Group you want to use for the bot, like the Server Admin group, and add the new identity to this Server Group
by clicking on Add and paste the new Unique ID here. Make sure that this server group has all needed permissions,
look at Needed Permissions for the bot in this readme file for a list.
Connect again with your TS3 client using the new identity, if not still connected.
If you connected to your server multiple times, make sure that the connection tab with the new identity is activated!
Now click on Tools -> ServerQuery Login and enter the login name, you like to have.
Write down the login name, you have chosen, and the password you got from the TS3 client.
Use this new details for the bot now. Make sure that you don't use this identity with your TS3 client anymore.
But keep it saved, because you can use it to change the query login password, if necessary some day.

Sometimes you should check my homepage, if there is a new version available for the JTS3ServerMod.
You can also activate the bot_update_check in the config/JTS3ServerMod_InstanceManager.cfg file,
to notify all clients on the bot_fulladmin_list about a new JTS3ServerMod version, as soon as they connect to the TS3 server.

In most cases you only have to replace the JTS3ServerMod.jar file, while the JTS3ServerMod process is stopped.
But you should take a look into the config/JTS3ServerMod_InstanceManager.cfg file, if there are new values,
which you like to copy over to your own file. But in most cases that config file changes are optional and not required.

But if the MySQL mode is disabled, I recommend to start the JTS3ServerMod with the argument -updateconfig after
replacing the JTS3ServerMod.jar file, that updates all bot configuration files!
Whole command: java -jar JTS3ServerMod.jar -updateconfig
Notice: This -updateconfig will also delete all lines of removed or renamed functions in the bot configuration files!

To know how to update the included PHP web interface, just read the webinterface/readme_webinterface.txt file.

For bug reporting, sending suggestions and testing a thanks flies to:
- 130ng0
- ADM24
- Adam M.
- Ahmet I.
- André A. / Kartoffel-Stampfer
- Atranox / End-Gaming.eu
- BEN89
- Baggavy J.
- Benjamin B.
- Benjamin L.
- BoKo / WebShell
- Bralosch
- ChoosenEye
- Chris / Orange Bots
- Christoph
- Christopher / Lenzen Networks
- Corba
- DaRkBoZ
- Daniel L.
- DarRoe
- DarkGhost
- David K.
- Denden / TSforYOU
- Dr.No
- DunklerKeks / Dark Empire Clan
- EidEchse
- FRAGGYNZ
- Fabrice
- Felix R.
- Flavio
- Flofus
- FoXFTW
- Frank B.
- Fusionpot
- GWR
- Gamle / MainGaming.dk
- Giftzwerg
- Guus W.
- Heiko
- Hermann W.
- Hinken
- HoschY1987
- Invictus International / TS Server HQ
- IronMC
- Jay / Clanwarz
- Jeremy P.
- Johannes1509
- KingHunt / Gamers Platoon
- Kirbyfan1223
- Lore
- MajorThorn
- Mariuszeq
- Marko M.
- Mateusz Z.
- Megamaluco
- Micha5
- Mikołaj
- MrChicken
- NaTesTa10
- NanooTec
- Nate4ever
- Nobody_cbm / Software Galaxy
- Pascal / Fierlord-Hosting
- Patschi
- Philip H. / squaX
- Pierre N. / Futuregamers.eu
- Prototype
- Raiden4918 / Subculture-Gaming
- Robert M.
- Robin B. / TS3-4You
- Rowtag
- Sandro M. / TS Voice
- Saucenteufel
- Sebastian S.
- SkullDrago
- Slater
- Speddyroot
- St3v3
- Stefan R.
- Surf3rDud3
- TS-Coach
- Taishou / NLFS Bündnis
- TeaTow
- Thomas / Science System
- ThomasHH / thl-online
- TotoIsBack
- Tukaa
- WaterFlow
- Yanek
- barricas
- cigaming
- dukio
- eggster
- elpoepel
- kadama / Oxivoice
- livedisco
- mastermax
- mathewitp / Old Dragons
- mthomas
- sojakfa
- thecrew
- tigerle
- whvler
- xeomueller / xgs.in
- xoun
...and much more!
List in alphabetical order.