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 chat 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 poke 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)
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.
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.
Java SE runtime environment version 5 or newer
You can get the latest version from www.java.com or http://java.sun.com/javase/downloads/index.jsp
Mac OS X 10.4 or newer users should have it already installed.
Linux users should install the package sun-java5-jre or sun-java6-jre (maybe openjdk-6-jre works also).
On debian based linux: apt-get install sun-java6-jre
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.
Most features needs at least Teamspeak 3 server beta 13,
but the record check feature needs at least Teamspeak 3 server beta 19.
And of course a possible connection to the Teamspeak 3 server.
By default there are two main config files, JTS3ServerMod_InstanceManager.cfg and JTS3ServerMod_server1.cfg.
The JTS3ServerMod_InstanceManager.cfg contains all informations about bot instances,
which should be started. The JTS3ServerMod_server1.cfg contains the bot settings of an 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. Linux users can run this tool even without X-Server.
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_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)
i_group_member_remove_power (Server Group Protection)
i_group_member_add_power (Server Group Protection)
i_client_modify_power (Server Group Protection)
i_client_kick_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_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 1024 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.
One solution is using screen. On debian based linux systems you can install screen (if not already) with:
apt-get install 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
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 Settings -> Options and
switch to the Application page (the first on top). 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!
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:
- BoKo
- Corba
- DaRkBoZ
- DarRoe
- Heiko
- HoschY1987
- MajorThorn
- mastermax
- Megamaluco
- Slater
- sojakfa
- St3v3
- tigerle
- TotoIsBack
List in alphabetical order.
Version 3.3.7 Final (28.09.2010)
- Bugfix: Complain was not added if someone was kicked after start recording. (thx to Thomas Z.)
Version 3.3.6 Final (27.09.2010)
- Bugfix: Small error releated to the mute mover was fixed.
- Bugfix: Better error messages on bad config files.
- Bugfix: Fixed NullPointerException if stopping virtual bot instance while connecting with slow mode enabled.
o Added permission id to logfile output, if a missing permission is reported by the TS3 server.
Version 3.3.5 Final (11.09.2010)
+ Some features can now add a complain to the user, if enabled.
This allows the server admin to see violating clients at the complain list window.
IMPORTANT: Do not use this feature on servers older than beta 28,
or it can break your complain system, if the bot login as serveradmin.
o Startup messages writes more informations about the enabled features.
o Added new optinal config values: record_add_complain, badnickname_add_complain and servergroupprotection_add_complain
Look into the documentation or default config file to get more informations about it.
Version 3.3.4 Final (04.09.2010)
o Server Group Protection now writes an error message into the log, if something is going wrong. (thx to TotoIsBack)
o Slow Mode is now more slower at connection (takes up to 16 seconds to connect now).
Should now work with stronger Anti-Flood protection settings of the TS3 server.
Version 3.3.3 Final (17.08.2010)
o Bot replace now for incoming chat messages the wrong space char from TS3 client history with the normal space.
o Some small changes to the reconnect / disconnect code.
Version 3.3.2 Final (10.08.2010)
o Changed the connecting order, now the bot login first after connection.
o Some small changes at the log output.
Version 3.3.2 Beta 1 (08.08.2010)
- Bugfix: Now the bot should also work if only Mute Mover, Server Group Protection, Bad Channelname or Bad Nickname Check is activated.
- Bugfix: Critical errors while requesting client or channel lists start the bot reconnecting countdown.
This should also solve the problem if only the virtual TS3 server will be stopped. (thx to TotoIsBack)
o Some messages on logfile should now give more and better informations.
Version 3.3.1 Final (03.08.2010)
o Some additions to the readme files.
o No changes at the bot, only version bump.
Version 3.3.1 RC 3 (02.08.2010)
- Bugfix: Idle warning message will be sent only once again. (thx to etonline)
Version 3.3.1 RC 2 (31.07.2010)
- Bugfix: Idle second message was not found, if enabled. (thx to Slater)
Version 3.3.1 RC 1 (30.07.2010)
+ Added new chat command: !botinstancelistreload
This reloads the instances. New loaded instances will be not started, use !botinstancestart for this.
+ Added new values for the Mute Mover, can now move if headphone or microphone hardware is disabled.
o 2 new config values was added to JTS3ServerMod_server1.cfg (mute_move_headphone_hardware and mute_move_microphone_hardware), see default config file.
Version 3.3.0 (29.07.2010) - Many bugs introduced here, do not use this version!
+ Added settings to many places to allow you to choose how a message will be shown at the client (poke, chat or no message).
- Bugfix: Config value servergroupprotection_kick was not read, this is now fixed.
- Bugfix: Implemented an error message if the bad channel name check is unable to get the channel list. (thx to TotoIsBack)
o 6 new config values was added to JTS3ServerMod_server1.cfg (for the message modes), see default config file.
Version 3.2.6 (26.07.2010)
+ Added setting to disable the server group protection kick, added config value servergroupprotection_kick for this.
o Added "bot successful started" message to console and log file.
o Updated documentation to make some things clear.
o Config value servergroupprotection_kick added to JTS3ServerMod_server1.cfg, see default config file.
Version 3.2.5 (13.07.2010)
- Bugfix: Fixed small bug at the chat commands !lastseen and !clientsearch (now case insensitive). (thx to MajorThorn)
Version 3.2.4 (09.07.2010)
- Bugfix: Fixed small bug while handle welcome message for a disconnected client. (thx to Slater)
Version 3.2.3 (30.06.2010)
- Bugfix: Fixed some bugs at the log output. (thx to Slater)
Version 3.2.2 (30.06.2010)
- Bugfix: Idle Check don't send warning messages to ignored server group members anymore. (thx to Mikobiko)
Version 3.2.1 (22.06.2010)
o Config value command_exec removed from instance config and moved to new value bot_command_exec in InstanceManager.cfg file.
Version 3.2 Final (18.06.2010)
+ Added feature to server group protection: If wanted, this feature adds missing server groups to client.
- Bugfix: Corrected the output of some logfile entries.
o Added new option servergroupprotection_add_missing_groups to JTS3ServerMod_server1.cfg, see default config file.
Version 3.1.1 Final (08.06.2010)
+ Added new option: Slow Mode
o Added more informations to the readme.txt file
o Bot writes more informations if something is wrong with the config file.
o Added optional value bot_slowmode to JTS3ServerMod_server1.cfg, see default config files.
Version 3.1 Final (23.05.2010)
+ Added a new help file in english and german language. Also translated the readme.txt into german language.
o Corrected some informations in the config files.
Version 3.1 RC 2 (16.05.2010)
o Changed loading of JTS3ServerMod_InstanceManager.cfg file, now a gab of 10 numbers in the consecutive numbering is allowed.
Version 3.1 RC 1 (14.05.2010)
+ Added a second type of bot admin. The full admin is the same as before and is set in the instance manager config file now.
The bot admin set in the server config file of the bot just allow bot commands which affect only the own bot instance.
o More informations in the log file, if an error occur.
o Added optional value bot_fulladmin_list to JTS3ServerMod_InstanceManager.cfg file, see default config files.
Version 3.0.2 Final (30.04.2010)
o More flexible with numbers in config files (removes spaces).
Version 3.0.1 Final (29.04.2010)
- Bugfix: Bad log entries of the Mute Mover.
Version 3.0 Final (23.04.2010)
o No changes since RC 8.
Version 3.0 RC 8 (22.04.2010)
+ New Feature: Mute Mover, can move clients if microphone or headphone is muted.
o Some values added at the bottom of the config file. Look into standard config file.
Version 3.0 RC 7 (17.04.2010)
+ Added minimum client count to idle check.
o Added value idle_min_clients to the idle check block in the config file.
Version 3.0 RC 6 (14.04.2010)
o Updated the Server Query Library, which improve the detection if the bot is still conntected to the TS3 server.
Version 3.0 RC 5 Hotfix (14.04.2010)
- Bugfix: Telnet clients was still reported by !lastseen as online. (thx to sojakfa)
Version 3.0 RC 5 (14.04.2010)
o The client database cache (used for !clientsearch and !lastseen) does only update real clients and no telnet users.
Suggested by sojakfa.
Version 3.0 RC 4 (12.04.2010)
+ New Chat Command: !botversioncheck displays the latest final and development version (bot needs internet access for this).
- Removed helptext about removed chat commands from !bothelp chat command.
Version 3.0 RC 3 (11.04.2010)
- Bugfix: Chat command !botcfgsave and !botreload was not working anymore, if advertising feature was enabled. (thx to Megamaluco)
- Bugfix: Advertising feature shows wrong interval in minutes on shell / cli window and log file. (thx to Megamaluco)
- Bugfix: Some log file entries missed some informations.
o Second exe file to start the bot for Windows users, but without a visible window (java runtime still needed).
Version 3.0 RC 2 (10.04.2010)
+ Improved: Chat command !botcfghelp can now display config keys which start with specified characters.
Example: !botcfghelp bot
This will display all config keys starting with the word bot.
Version 3.0 RC 1 (10.04.2010)
- Bugfix: !botcfghelp command works now again.
- Bugfix: !botcfgreload did not work correctly.
Version 3.0 Beta 3 (09.04.2010)
+ New Feature: Server Group Protection
+ New Chat Command: !botcfgreload to reload one of the special config files (advertising, idle, welcome, etc.).
- Removed: Chat command !botadvmsgreload replaced with "!botcfgreload advertising".
o Some values added at the bottom of the config file, one new config file also added. Look into standard config file.
Version 3.0 Beta 2 (08.04.2010)
- Bugfix: Fixed !botreload command (thx to Slater)
Version 3.0 Beta 1 (07.04.2010)
+ New Feature: Bad Nickname Check, which uses regular expressions.
+ New Feature: Bad Channel Name Check, which uses regular expressions.
o Some internal changes to make sure that there is no XServer call on operating systems without graphical user interface. (thx to HoschY1987)
o Some values added at the bottom of the config file, two new config files also added. Look into standard config file.
Version 2.1 Final (02.04.2010)
- Bugfix: Advertising to server chat did not work if virtual server got selected by port. (thx to mastermax)
Version 2.1 RC 3 (20.03.2010)
- Bugfix: New line (\n) was not displayed in messages correctly (thx to Heiko).
o Important: Don't save the messages files in unicode with BOM, it will not work.
Just use unicode without BOM and the UTF-8 encoding will work.
Version 2.1 RC 2 (18.03.2010)
o All messages are now in external files, which can be loaded with a different character encoding.
Default encoding for messages files is now UTF-8, which can be changed in config file.
o Many config file changes, please take a look on the default config files.
Version 2.1 RC 1 (18.03.2010)
- Bugfix: advertising.cfg will be now loaded with encoding ISO-8859-1 like the other bot config files.
This should solve the wrong display of special characters.
Version 2.0 Final (12.03.2010)
o No changes since RC 1.
Version 2.0 RC 1 (09.03.2010)
+ New: Chat command !botreloadall - Reloads all bot instances (without checking config files).
o Internal changes and optimizations. The bot needs now TS3 server beta 19 or newer for record check.
The advantage: Bot needs now much less telnet commands to do the work.
Version 2.0 Beta 7 (01.03.2010)
+ New: Second idle message as kick reason after being idle for longer than idle_second_max_time.
- Bugfix: Some smaller bugfixes at all idle check features.
o Config changes: New argument idle_second_message, look into the default config file.
Version 2.0 Beta 6 Hotfix (28.02.2010)
- Bugfix: Second idle time kick was not working.
Version 2.0 Beta 6 (28.02.2010)
+ New: Idle mover got a new argument to kick after a second idle time.
- Bugfix: Fixed some bugs with !execwait
o Config changes: New optional argument idle_second_max_time, look into the default config file.
Version 2.0 Beta 5 (27.02.2010)
+ New: Define now many advertising messages in a file.
+ New: Chat Command !botadvmsgreload to reload advertising messages file without reconnect bot.
- Bugfix: !exec and !execwait was not working, this is now fixed.
o Exe file to start the bot for Windows users (java runtime still needed)
o Config files by default now in a config directory.
o Config file changes: advertising_message removed, advertising_file added. Look into the default config!
Version 2.0 Beta 4 (26.02.2010)
- Bugfix: Idle warn message and idle move was not working correct if idle_check_enable was set to 2 (thx to DarRoe)
Version 2.0 Beta 3 (25.02.2010)
+ New: Away mover can now move back, if away_check_enable is set to 2
+ New: Chat command !clientsearch for bot admins, which works like the !lastseen command, but outputs more informations about the client.
Version 2.0 Beta 2 (24.02.2010)
+ New feature: Chat command !exec and !execwait - Bot admin can execute a system command, can be enabled in config file.
+ New: Client database cache for commands like !lastseen. This makes this commands much faster on big servers.
+ New: Now its possible to change the away move delay in config file.
+ New: Idle check can now also kick and ignore server groups.
o Bot will now disconnect clean from Teamspeak server on system shutdown or when sending CTRL + c to bot process.
o Added config values: bot_clientdblist_cache, command_exec, idle_ignore_groups and away_move_delay. Look into the default config!
IMPORTANT: Config value idle_check_enable has changed. Look into the default config!
Version 2.0 Beta 1 (22.02.2010)
+ New feature: Chat command !msgchannelgroup - Sends a message to all online clients with this channel group.
+ New feature: Chat command !msgservergroup - Sends a message to all online clients with this server group.
+ New feature: Chat command !removechannelgroups - Change all channel groups of a client to the default channel group.
Version 1.0 Final (21.02.2010)
- Bugfix: If a start error in a bot instance occurred, the whole bot process quits. This is now changed, only the bot instance stops working.
o The instance manager checks now if the config file exists. If not, a special error message will be displayed.
o Changed the text output on the command line.
Version 1.0 RC 5 (19.02.2010)
+ New feature: Chat command !lastseen to see somebody's last online time. Possible to disable this for public use.
+ New: Bot Instance Manager, start many bot instances for different Teamspeak 3 servers with one bot process.
+ New: Admin chat commands !botcfghelp, !botcfgget, !botcfgset, !botcfgcheck, !botcfgsave, !botinstancestart, !botinstancestop and !botinstancelist
+ New: !bothelp can now display an info text about a command.
- Bugfix: Default welcome message did not work if the second welcome message is disabled. (thx to DarRoe)
o Added connect message, if the connection to Teamspeak server is successful.
Version 1.0 RC 4 (17.02.2010)
+ New: Now its possible to use the virtualserver port to select the virtual server.
- Bugfix: Record kick did not work since 1.0 RC 2, this is now fixed. (thx to DarRoe)
o Config key name ts3_server_port changed to ts3_server_query_port to avoid confusion.
Version 1.0 RC 3 (17.02.2010)
+ New feature: Second welcome message for specified server groups.
+ New: More keywords for the welcome message, like the unread offline message count.
+ New: Change date pattern for welcome messages and future date formatting on chat commands.
+ New: If enabled, the bot can try to connect to an offline Teamspeak 3 Server forever.
+ New: You can choose a second server query name, if the first name is already in use.
- Bugfix: Bot do not quit now if only the bot name is already in use.
Version 1.0 RC 2 (16.02.2010)
+ New: Exclude Server Group members from record check
+ New: Shows bot uptime on !botinfo
- Bugfix: Start errors was not written to logfile.
o Bot now also checks if channel IDs in config file exists. If not, bot shows a warning and disables feature.
Version 1.0 RC 1 (15.02.2010)
+ New feature: Idle warning message
+ New feature: Auto away mover
- Bugfix: !botreload did not work.
- Bugfix: Auto reconnect did not work in every cases.
o Changed and completed status output on console and logfile.
Version 1.0 Beta 3 (14.02.2010) - Not released
+ New feature: Welcome Message
+ New feature: Server commands like !botinfo and !bothelp
+ New feature: Bot can switch to a channel on connection.
+ New feature: Bot reconnects automatically after some time, if connection lost.
o Changed config loading again, now more failsave and better error messages.
Version 0.9.1 Beta 2 (11.02.2010)
+ Selected channels can be ignored for idle and record check.
+ New feature: Advertising
o Changed config loading, only needed values will be loaded.
Version 0.9 Beta 1 Hotfix (11.02.2010)
o Just updated the ServerQuery library, which do not generate more warnings in the Teamspeak 3 server log.
Version 0.9 Beta 1 (11.02.2010)
- First public Beta version