funtimecoding/seat-teamspeak

This plugin provide an extension to the standard SeAT character Job which handle automatic graduation for Teamspeak user

5.1.0 2021-01-14 12:50 UTC

Requires

• ext-json: *
• warlof/seat-connector: ^2.1

GPL-3.0-or-later

• Warlof Tutsimo
• Denngarr B'tarn
• hderp886

README

This plugin write for SeAT is providing to your instance a way to manage your Teamspeak with SeAT using both query and a grant permission system.

Requirements

• In order this driver works with Teamspeak, the target Teamspeak Server must be 3.12.x or newer. Be sure you're running latest version
• REST Api must be enabled on the Teamspeak Server (either http or https query protocole) - see instructions bellow

Installation

Package deployment

Bare metal installation

In your seat directory (by default: /var/www/seat), type the following:

php artisan down
composer require warlof/seat-teamspeak

php artisan vendor:publish --force --all
php artisan migrate
php artisan up

Now, when you log into SeAT, you should see a Connector category in the sidebar.

Docker installation

In the directory where reside your docker-compose.yml file, edit the .env configuration file (by default: /opt/seat-docker/.env)

Find the line SEAT_PLUGINS and append warlof/seat-teamspeak:^5.0 at the end.

• In case the line is starting by a sharp #, replace the line by SEAT_PLUGINS=warlof/seat-teamspeak:^5.0
• In case you already have other plugins defined, append a comma at the end of existing value SEAT_PLUGINS=author/package,warlof/seat-teamspeak:^5.0.

Once done, you can restart your stack using docker-compose up -d.

Teamspeak Server Configuration

Access your Teamspeak server and find the query_ip_whitelist.txt file. Add the IP address of your Seat install server to the list to avoid flood bans when running jobs. Don't forget to add an empty line at the end of the query_ip_whitelist.txt.

If it's not already the case, you will have to enable either http or https protocol to allow server queries. This can be done by appending one or the other to TS3SERVER_QUERY_PROTOCOLS environment variable (if using Docker) or query_protocols as startup parameter (if using a blade installation).

CAUTION

The used IP address must be the one SeAT will use to contact your Teamspeak server. In case you have a private network linking both servers, and you plan to ask SeAT to contact the teamspeak instance on this network, you must add the SeAT private IP from that network instead its public IP address.

Once this configuration has been done, we will generate an API Key which will be used by SeAT to send his commands to Teamspeak. To do so, authenticate on the teamspeak server using serveradmin account with a tool of your choice (ie: putty or YaTQA)

1. Authenticate against server using login serveradmin ${serveradminpassword}
2. Generate new API Key for SeAT using apikeyadd scope=manage lifetime=0

The server should answer with something similar

TS3
Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help <command>" for information on a specific command.
error id=0 msg=ok
apikey=BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j id=4 sid=0 cldbid=1 scope=manage time_left=unlimited created_at=1582102492 expires_at=1582102492
error id=0 msg=ok

In the upper example, the generated API Key is BAByFoiEXZfnSJyE6dbXFiW_nn_SdwkclpKNz9j. This is the piece you will need to set up the connector into SeAT.

Connector Setup

Authenticate on your SeAT instance with an admin account. You can use the built-in administrator user using php artisan seat:admin:login which will provide you proper permissions.

On the sidebar, click on Connector and then click on Settings.

Change the Configuration to meet your Teamspeak server's settings into Teamspeak block.

• Server Address: is the address your user will use to connect to your Teamspeak instance (it can be either an IP or a domain)
• Server Port: is the port your user will use to connect to your Teamspeak instance (9987 by default)
• Api Base Uri: is the url that SeAT will use to contact your Teamspeak Server (by default http://teamspeak_address:10080 or https://teamspeak_address:10443)
• Api Key: this is the key you generated in previous steps

Initializing

Authenticate on your SeAT instance with an admin account. You can use the built-in administrator user using php artisan seat:admin:login which will provide you proper permissions.

On the sidebar, click on Connector and then click on Settings.

In the driver dropdown list, select Teamspeak and click on Update Sets button which will queue a job to pull all of your currently defined server groups.

Access are grant through the Access Management section.

Scheduler

Authenticate on your SeAT instance with an admin account. You can use the built-in administrator user using php artisan seat:admin:login which will provide you proper permissions.

On the sidebar, click on Settings and then click on Schedule.

• add seat-connector:apply:policies (recommended every 30 minutes)

In order to grant access to Identities section, you must add permission seat-connector.view to a role you're assigning to your users.

Query Permissions

You'll find below a list of required permissions and used query patterns

Query	Server Permission	Api Scope
/serverlist	b_serverinstance_virtualserver_list	manage
/{instance}/clientdbfind	b_virtualserver_client_dbsearch	manage
/{instance}/clientdbinfo	b_virtualserver_client_dbinfo	manage
/{instance}/clientdblist	b_virtualserver_client_dblist	manage
/{instance}/servergroupaddclient	i_group_member_add_power	manage
/{instance}/servergroupsbyclientid		manage
/{instance}/servergroupclientlist	b_virtualserver_servergroup_client_list	manage
/{instance}/servergroupdelclient	i_group_member_remove_power	manage
/{instance}/servergrouplist	b_virtualserver_servergroup_list	manage
/{instance}/serverinfo	b_serverinstance_help_view	manage