fechnert / ts3observer

Observe a TeamSpeak3 Server and Manage clients, groups and channels

ts3observer

The ts3observer (teamspeak 3 observer) is a plugin-based tool to observe a Teamspeak 3 Server. It allows you to interact with clients, groups and channels. For example, move clients if they are idle, kick clients with unwanted nicknames or simply message a group if some client complaints about another.

For more information, examples and developer information, read the Wiki.

Installation

First you need to clone the tool:

git clone [email protected]:HWDexperte/ts3observer.git

After that, you need some requirements:

sudo apt-get install python python-yaml pip
pip install -r requirements.txt

Configuration

After a successful installation, you need to configure the ts3observer with the main configuration file unter conf/.

You should copy the ts3observer.yml.skel to ts3observer.yml and modify the new file to match your settings.

Usage

You can run the ts3observer with python ts3observer.py run.

To view all available commands, type python ts3observer --help

Plugins

Since the ts3observer is plugin based, every tasks that manages clients, channels or groups should be delegated to plugins. One plugin should cover one topic of tasks.

There are already some Plugins available.

You can add plugins by copying the plugin.py in the plugins/ folder while the ts3observer is not running.

If you now start the ts3observer, it will "load" all plugins it can find in the plugin folder.

If it finds any new plugins (plugins without a config file), it will create a default config in the conf/ folder, log the new plugin as '[NEW]' and stops after all plugins are loaded and initialized to allow you to configure the new created config files.

Important notes

It is recommended to run the ts3observer locally on the server where your teamspeak server in running. You can run it remotely, but then you have to write the IP address of the remote server to teamspeak's query_ip_whitelist.txt.

To avoid all this mess, simply make sure that ts3observer is running beside the teamspeak server and that a local IP adress like localhost or 127.0.0.1 is written in teamspeak's query_ip_whitelist.txt. Should be by default.

ts3observer's Issues

Observer crashes

https://gist.github.com/stphnrdmr/83e305bc98e1a82e4c24626a3e8aaa7d

Notifications for complaints

Send a private message to a specific groups(s) or client(s) if someone submits a complaint

Critical Exception if client disconnects

The ts3observer will raise a QueryFailedException with message

The Query 'clientinfo clid=0' failed! ErrorID: 512, ErrorMsg: 'invalid clientID'

This is because if an Action is build and registered but the client disconnects after a action is marked for execution and the point where an action actually should be executed, there will be no more this client id

Can't black- or whitelist Groups

It is not possible to set a Base- or Feature specific white and/or blacklist for groups

Give features a brain

Give features a possibility to remember some stuff ...

OnOther

If clients are also on a other server but they're "muted" on yours, is that an other status?

Web frontend

Design a web frontend to edit configuration of features or show stats or etc ...

OnIdle

Treat clients if they're idling for too long.

Teamspeak's definition of Idling is if you say nothing.

Add actions to modify groups

ts3observer should become Actions to modify the groups of clients

group_set
group_del
group_add

Note: Actions should check if client already have (removed) group or else

Implement descriptive actions

To allow plugin developers a easier way to let users fully configure actions, there should be a way to generalise the config handling.

Exception if permissions to low

The user which is used as queryadmin login currently must have the highest permissions needed on the server.

For example:
You are the admin, needed_ban_power=100
the bot, ban_power=90

Bot cannot ban the admin.
Ugly workaround is to exclude such users with the blacklist rule from features which need more permissions (ban)

Implement Timed action execution

TL;DR, do stuff

Feature based client managing

Build different features (here labeled as feature) which manages clients in specific ways

Channel white- / blacklist won't work properly

The white- and blacklist check for channels won't work properly.

Multiple actions for one Feature

Should it be possible to configure multiple actions for one Feature like this:

FeatureXY:
  enable: True
  execute1:
    action: move
    to: 42
    s_delay: 10
  execute2:
    action: kick
    reasonid: 5
    m_delay: 60
    reason: "Idled too long!"

Features share rules

Features can't have specific rules

Let the Authenticater write down last seen info

The Authenticator plugin should write down a timestamp and the nickname the client had at he was last seen of the ts3observer

Nickname not properly read

If the nickname / username of a client contains a =, the nickname will be only the part until this char.

Implement a PlugIn - System

Dump the Idea of Features and Listeners.
Implement Plugins!

Every Plugin should cover a topic or task.

Extra: Make Plugins pluggable!

Integrate argparse

Use the library argparse to specify some parameters like the verbose level on startup

Global config file will reset plugin configuration after restart

After a new plugin was found and the ts3observer stopps to enable the configuring of the new plugin, the global config file 'ts3observer.yml' will be resetted to its default configuration.

For example, the Authenticater Plugin

Better feature logic part

Be surprised of this commit 💎

OnMute

Treat clients if their microphone is muted

Move telnet stuff to own module

Move all telnet stuff like connecting to server or else to a own module.

Force unwanted music bots to 'push-to-talk'

Create a Plugin that forces every client which talks straight for like 10 minutes to 'Push-to-talk' mode.

But enable a blacklist of UID's for clients which are allowed to run a music bot

Joining the afk channel immediately kicks the person from it

When I join the afk channel I am immediately moved back to the channel I came from.

Critical: KeyError if client in movebackqueue disconnects

An KeyError Exception is raised if an client which is in a the moveback queue disconnects

split client and channel features

Because there are a lot of channels on a standard ts3-server, features of clients and channels should be splitted.

client features still can be called every second,
but it makes sense to check channel features only every 10 minutes or every hour.

This should prevent the bot from wasting time in expensive channel operations.

Validation for action assignment

A Feature should validate the queue and the action it want's to assign to ensure validity.

• should warn user if a action is configured that doesn't exist
• should check if action is not needed
  • for example: don't move if user already in to channel
  • don't add group if user already has group

Check plugin version before runnig it again

If the version of a plugin changes after it is already configured, the user of the ts3observer will not be informed about this change and the ts3observer will crash if the config change was neccessary to work properly

Timed Channels

Create channels for a configurable (and periodic) event.

Create at given time,
Delete after given event length

Authenticater wont remove group if uid is missing in database

The authenticater Plugin should remove all rights set via database from client if there is not associated uid

Exception if socket not properly read

The Supervisor throws a exception if the socket is not properly read and a Client with uncomplete attributes is generated

move action should move back

The move action should be able to move clients back if the feature doesn't trigger anymore

delayed features

Already seen in config, features should have a delay option to affect objects.

there should be two delay options:

• s_delay: delay in seconds
• m_delay: delay in minutes

White- and Blacklist based Features

Features can affect clients and channels.

It's possible to either define a whitelist or a blacklist for a feature.

• whitelists
  only affect whitelisted clients or channels for this feature
• blacklists
  affect all clients or channels for this feature except the blacklisted

IdleMover breaks if moving to non existend channel

If you're in a temporary channel and you're moved out because of idling, then the channel you came from is deleted and the plugin wants to move you back, you'll get a QueryFailedException

| CRITICAL | QueryFailedException:
             The Query 'clientmove clid={clid} cid={cid} cpw=' failed!
             ErrorID: 768, ErrorMsg: 'invalid channelID'

Where {cid} = your not existing channel

OnAway

Treat clients if their status is set to away

Critical: GuiCli Breaks if client disconnects

The GuiCli throws an AttributeError: 'Client' object has no attribute 'client_nickname' Error.

This happens because the GuiCli references on the supervisors clients.

Add a warning system

It would be nice if there is the possibility to warn a user if a feature triggers.
If the user reaches a specific warning level, a additional feature should execute a configurable action on it.

new action: warn
new feature: WarnWatcher

AttributeError: 'list' object has no attribute 'split'

Traceback (most recent call last):
  File "./run.py", line 6, in <module>
    console.run()
  File "/home/admin/servers/ts3observer/ts3observer/cli.py", line 25, in run
    self.supervisor.execute()
  File "/home/admin/servers/ts3observer/ts3observer/observer.py", line 53, in execute
    clients = self._clientlist()
  File "/home/admin/servers/ts3observer/ts3observer/observer.py", line 95, in _clientlist
    clients.update(self.__build_client(raw_client))
  File "/home/admin/servers/ts3observer/ts3observer/observer.py", line 100, in __build_client
    clid = int(PropertyMapper.string_to_dict(raw_client.split('\r'))['clid'])
  File "/home/admin/servers/ts3observer/ts3observer/utils.py", line 73, in string_to_dict
    properties = arg_str.split(' ')
AttributeError: 'list' object has no attribute 'split'

Add note actions

Add some actions to write to a player

For example:
poke
chat

Provide some utils

Provide some utils to

• give a quick list of the servers channel-tree with channel-id's (teamspeak itself gives you no information about this. Can be used to determine channel id's for moving)
• test the configuration

Move clients to specific channel on event

Move clients in configurable channel(s) if

• their status is away for more than x seconds
• they're talking nothing for x minutes (idle)
• their microphone / speaker / headset is disabled for x seconds
• they're to long in specific channel(s) (Used to avoid lobbycamping?)
• they're on antoher server

Kick clients by name blacklist

Kick specific members with unwanted usernames by a blacklist

OnDeaf

Treat clients if their headset is muted (=deaf)

Group white- / blacklist rules won't work properly

The white- and blacklist check for servergroups don't work properly.

Detect musicbots and demote them

Detect clients which sends over x minutes straight and claim them as musicbot.
MusicBots will be demoted and can be kicked out of the channel by verified clients (members)

Querys take to long

It's currently not possible to query a server and all clients and channels every second, because i must wait 0.1 second per query ... Should be fixed if i use sockets

Features should can write to socket

Features schould have the possibility to write to the telnet-socket. Used for uncommon features like #16