Author: Stefan Martens
E-Mail: info@stefan1200.de
Homepage: http://www.stefan1200.de
JavaScript needs to be activated in your Browser to display this help file.
Table of contents:
This program adds some functions to the Teamspeak 3 server. Here is the feature list:
- Server Group Protection to kick people which are unauthorized member of a protected server group (since version 3.0)
- Bad nickname check to kick people with a bad name from the server (since version 3.0)
- Bad channel name check to delete channels with a bad name (since version 3.0)
- Move idle users to another channel and sends a text message
- Kick idle users with a kick reason (since version 2.0)
- Send a warning message if someone is idle
- Move to a specified channel if client status is away (after some seconds idle),
can move back if not away anymore (move back since version 2.0)
- Move to a specified channel if client status is headphone or microphone muted (after some seconds idle),
can move back if not muted anymore (since version 3.0)
- Move recording users to another channel and sends a text message
- Kick recording users from server with a kick reason
- Send a message every X minutes to virtual server or a special channel
- Send a welcome message to every connecting client, can send a special welcome message to specified server groups
- !lastseen chat command to see somebody's last online time
Anything can be configured in a config file.
Another features are:
- Many bot instances for different Teamspeak 3 servers in one bot process
- Automatic reconnect after connection to Teamspeak 3 server lost
- Chat commands which allows you to change configurations, reload config file, quit the bot and much more.
- Slow Mode to use the bot (with limited features) without changing the query_ip_whitelist.txt file. (since version 3.1.1)
This program runs on Windows and Linux (even without X server). On Mac OS X 10.4+ it should run too, but it is not tested.
Please send me a message if this bot runs on Mac OS X without problems.
All you need is a Java SE runtime environment version 5 or newer.
You can get the latest version from www.java.com or http://www.oracle.com/technetwork/java/...
Mac OS X 10.4 or newer users should have it already installed.
Linux users should install the package sun-java6-jre or openjdk-6-jre (on older linux you can also use sun-java5-jre).
An example on Debian or Ubuntu linux: apt-get install sun-java6-jre
An example on CentOS or Fedora: yum install java-1.6.0-openjdk
An example on OpenSUSE: yast -i java-1_6_0-sun
The package gcj-jre (GNU Java) will not work!
Maybe you want to limit the maximum ram that the bot use. This can be usefull 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. 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 beta 19 or newer is needed, but I recommend at least beta 28.
And of course a possible connection to the Teamspeak 3 server.
Notice:
You should add the IP address of this program 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 to connect to the TS3 server.
Because 127.0.0.1 is white listed by default. Make sure that the query_ip_whitelist.txt file have an empty line at the end.
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 there are two main config files, JTS3ServerMod_InstanceManager.cfg and JTS3ServerMod_server1.cfg.
The JTS3ServerMod_InstanceManager.cfg contains all informations about virtual bot instances,
which should be started. The JTS3ServerMod_server1.cfg contains the bot settings of a virtual instance.
So open both config files and change it to fit your needs. Everything is explained there.
But make sure that you save both files in ANSI format (encoding ISO-8859-1) and not unicode.
Important: All other config files (like the advertising, record, idle and welcome messages)
are saved in unicode (without BOM) by default. You can change this encoding in the main config 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
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.
Make sure that the following permissions are granted for the bot (in brackets why this permission is needed):
b_virtualserver_channel_list (Always needed)
b_virtualserver_client_list (Always needed)
b_virtualserver_client_dblist (Client Database Cache)
b_virtualserver_notify_register (Always needed)
b_virtualserver_servergroup_list (Server Group Notify & Server Group Protection)
b_serverinstance_permission_list (Displaying missing permission names in log)
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_delete_flag_force (Bad Channel Name Check)
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_join_ignore_password (Allow joining all channels)
i_channel_join_power (Allow joining all channels)
i_group_member_remove_power (Server Group Protection)
i_group_member_add_power (Server Group Protection)
b_group_is_permanent (The bot stay at this group after reconnecting)
i_client_modify_power (Server Group Protection)
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_complain_power (Many functions if complain is enabled)
i_client_poke_power (Many functions if poke is choosen as message mode)
i_client_private_textmessage_power (Always needed)
b_client_channel_textmessage_send (Advertising)
b_client_server_textmessage_send (Advertising)
b_client_info_view (Welcome Message)
b_virtualserver_select (To connect)
May be needed in later version:
b_virtualserver_info_view
The Guest Server Query group also needs:
b_serverquery_login (To connect)
You can choose different message types for the most functions of the bot,
check the default JTS3ServerMod_server1.cfg file for this.
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 all configuration files of this bot, which must be changed to fit your needs.
Important settings at the config file JTS3ServerMod_server1.cfg,
you must set them right to make sure that the bot will work:
ts3_server_address
ts3_server_query_port
ts3_server_query_login
ts3_server_query_password
ts3_virtualserver_id / ts3_virtualserver_port
bot_slowmode
By default all functions are disabled. Activate them like you want.
But be careful with the following functions, because wrong configuration can make big problems:
bad nickname check
bad channel name check
server group protection
If one or more persons should be bot admins, you must set one of the following settings:
Bot Full Admin (all admin commands): JTS3ServerMod_InstanceManager.cfg -> bot_fulladmin_list
Bot Admin (only admin commands of the virtual bot instance): JTS3ServerMod_server1.cfg -> bot_admin_list
Now all important settings are done. Save all files, but make sure that you save both files
in ANSI format (encoding ISO-8859-1) and not unicode. All other config files (like the advertising,
record, idle and welcome messages) are saved in unicode (without BOM) by default.
You can change this encoding in the config file JTS3ServerMod_server1.cfg -> bot_messages_encoding.
To start the bot 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.
If wanted, you can run the bot as Windows Service, this is a little bit more complicated.
To do so, if not already installed, download the Windows Server 2003 Resource Kit Tools:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=9d467a69-57ff-4ae7-96ee-b18c4790cffd&displaylang=en
You may get a warning message on newer Windows versions, but on my Windows 7 system anything worked.
Now install the Windows Server 2003 Resource Kit Tools.
For the next steps I prepared a small script which do anything for you.
In the tools sub directory you find the script InstallWindowsService.cmd,
but you have to change that script a little bit. To do this just open that script in a text editor.
The path ResourceKitPath and JTS3ServerModPath must be changed to match your installation.
After saving this changes just run this script with Administrator permissions.
The last step is to start the Service like displayed at the end of this script.
Important:
The Service can start the bot, but not stop it again.
You can do this by a chat command to the bot or with the Task Manager.
One solution is using screen. Installing screen is easy (if not already):
On Debian or Ubuntu:
apt-get install screen
On CentOS or Fedora:
yum install screen
On OpenSUSE:
yast -i screen
After you did this, you can change to the JTS3ServerMod directory with cd and fire the following command:
screen -d -m -S ts3bot java -jar JTS3ServerMod.jar
This starts the bot in a special shell screen named ts3bot.
To open this shell screen named ts3bot, maybe to read the output of the bot, just do:
screen -r ts3bot
To close an opened shell screen without quitting the Bot just press the following key combination:
CTRL + A + D
If you run into problems, check the section System requirements in this readme file.
It is possible to reduce the amount of memory the bot may use.
This is important on Linux VServers.
The low memory example from there to start the bot with the screen command:
screen -d -m -S ts3bot java -mx30M -jar JTS3ServerMod.jar
Since version 1.0 it is possible to use some bot commands in the chat of the Teamspeak 3 server.
You can use the server, channel or private chat. Of course you have to be in the same channel for the channel chat.
To 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
To be a bot admin, you must enter your public unique ID of your client in the bot config file.
Since bot version 3.1 there are two different bot admins possible.
You can set full admins in the JTS3ServerMod_InstanceManager.cfg file,
normal bot admins are set in each bot instance config file for every server.
Full bot admins can use all bot commands on every bot instance.
Normal bot admins are limited to the own bot instance and cannot use the following commands:
!exec, !execwait, !botquit, !botinstancelist, !botinstancestart, !botinstancestop
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 bot instances.
Each bot instance can create an own log file, this can be set in JTS3ServerMod_InstanceManager.cfg for every bot instance.
A bot instance logs all actions on Teamspeak server and of course all errors while doing this.
This program is free for use, but please notify me if you found a bug or if you have some suggestion.
The author of this program is not responsible for any damage or data loss!
It is not allowed to sell this program for money, it has to be free to get!
It is also not allowed to use my source code and publish that with your name!
Please ask me for a permission first if you want to publish something which contains parts of my source code!
Teamspeak 3 is developed by TeamSpeak Systems GmbH, Sales & Licensing by Triton CI & Associates, Inc.
More informations about Teamspeak 3: http://www.teamspeak.com
For bug reporting, sending suggestions and testing a thanks flies to:
- Benjamin
- BoKo / WebShell
- Corba
- Chris / Orange Bots
- Christoph
- DaRkBoZ
- DarRoe
- EidEchse
- Flavio
- Heiko
- HoschY1987
- KingHunt / Gamers Platoon
- MajorThorn
- mastermax
- Megamaluco
- Nate4ever
- Slater
- sojakfa
- St3v3
- Thomas / Science System
- tigerle
- TotoIsBack
List in alphabetical order.