161 lines
7.2 KiB
Markdown
161 lines
7.2 KiB
Markdown
# Linux TeamSpeak Bot
|
||
|
||
A TeamSpeak 3 bot written in Node.js (using [`ts3-nodejs-library`](https://www.npmjs.com/package/ts3-nodejs-library)) that can receive commands in channels or private messages, authenticate users via token, and communicate with a custom API to perform various container and server operations.
|
||
|
||
> **Table of Contents**
|
||
> - [Features](#features)
|
||
> - [Prerequisites](#prerequisites)
|
||
> - [Installation](#installation)
|
||
> - [Configuration](#configuration)
|
||
> - [Usage](#usage)
|
||
> - [Available Commands](#available-commands)
|
||
> - [Folder Structure](#folder-structure)
|
||
> - [Contributing](#contributing)
|
||
> - [License](#license)
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **TeamSpeak Connection**: Connects to a TS3 server as a Query Client bot.
|
||
- **Token Management**: Asks users for their API token via private message, and stores them securely in a JSON file.
|
||
- **API Integration**: Makes authenticated API calls (with a custom header `x-ssh-auth`) to manage a container (start, stop, restart, get stats/info, etc.).
|
||
- **Command Parsing**: In-channel commands prefixed with `!`, and private message commands.
|
||
- **Directory/Command Execution**: Allows users to run commands (`!x <command>`) inside the container and navigate directories (`cd`, `cd ..`, `cd ~`, etc.).
|
||
- **Extensible**: Easily add more commands or API endpoints.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
1. **Node.js (v14 or later)**
|
||
Make sure you have Node.js installed. You can check by running:
|
||
```bash
|
||
node -v
|
||
```
|
||
2. **TeamSpeak 3 server credentials**
|
||
- Hostname/IP
|
||
- Query Port
|
||
- Server Port
|
||
- Query Username & Password
|
||
3. **API Endpoint** (for container/server control):
|
||
- A valid base URL for the API (e.g., `https://your-api.example.com` or `http://localhost:3000`).
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
1. **Clone or download** this repository:
|
||
```bash
|
||
git clone https://git.ssh.surf/snxraven/sshsurf-ts3-bot.git
|
||
```
|
||
2. **Install dependencies** in the project directory:
|
||
```bash
|
||
cd sshsurf-ts3-bot
|
||
npm install
|
||
```
|
||
3. **Create configuration files**:
|
||
- `config.json`
|
||
- `tokens.json` (an empty file to store user tokens)
|
||
|
||
See [Configuration](#configuration) below for details.
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
You need two main JSON files to make the bot work:
|
||
|
||
1. **`config.json`**
|
||
An example configuration might look like this:
|
||
```json
|
||
{
|
||
"TS_HOST": "127.0.0.1",
|
||
"TS_QUERY_PORT": 10011,
|
||
"TS_SERVER_PORT": 9987,
|
||
"TS_USERNAME": "serveradmin",
|
||
"TS_PASSWORD": "supersecretpassword",
|
||
"apiBaseURL": "http://localhost:3000"
|
||
}
|
||
```
|
||
- `TS_HOST`: The IP/hostname of your TeamSpeak server.
|
||
- `TS_QUERY_PORT`: The query port (default is `10011`).
|
||
- `TS_SERVER_PORT`: The virtual server port (default is `9987`).
|
||
- `TS_USERNAME` & `TS_PASSWORD`: Your TeamSpeak query login credentials.
|
||
- `apiBaseURL`: The base URL of your custom API (for container operations).
|
||
|
||
2. **`tokens.json`**
|
||
This file stores the tokens per user, in JSON format. It’s empty or non-existent on first run:
|
||
```json
|
||
{}
|
||
```
|
||
The bot automatically populates this file with user tokens after requesting them via private message.
|
||
|
||
Make sure both files are located in the same directory where the bot is run.
|
||
|
||
---
|
||
|
||
## Usage
|
||
|
||
1. **Start the bot**:
|
||
```bash
|
||
npm start
|
||
```
|
||
or
|
||
```bash
|
||
node index.js
|
||
```
|
||
_(Adjust the filename if necessary.)_
|
||
|
||
2. **Check the console** for the bot’s output:
|
||
- It will print `TeamSpeak bot is ready and connected.` once fully started.
|
||
- When a user connects, it may request a token if one is not already stored.
|
||
|
||
3. **Interact in TeamSpeak**:
|
||
- Open your TeamSpeak client and connect to the same server.
|
||
- In a channel or server chat, prefix commands with `!` (e.g., `!hello`, `!stats`, etc.).
|
||
- If you don’t have a token on record, the bot will send you a private message prompting you to reply with your token. Just **reply without `!`** to that private message.
|
||
|
||
---
|
||
|
||
## Available Commands
|
||
|
||
All commands should be typed in a channel or server chat with an exclamation mark (`!`) prefix. Some **private message** commands (`!ping`, or direct token entry) are also available.
|
||
|
||
| Command | Description | Example |
|
||
|------------------------|---------------------------------------------------------------------------------------------------|----------------------------------|
|
||
| `!hello` | Calls `/hello` on the API and returns the “hello” message. | `!hello` |
|
||
| `!name` | Returns the username from the API (`/name`). | `!name` |
|
||
| `!stats` | Shows the container/server stats (`/stats`). | `!stats` |
|
||
| `!uptime` | Returns uptime information (`/uptime`). | `!uptime` |
|
||
| `!start` | Starts the container/server via `/start`. | `!start` |
|
||
| `!stop` | Stops the container/server via `/stop`. | `!stop` |
|
||
| `!restart` | Restarts the container/server via `/restart`. | `!restart` |
|
||
| `!info` | Shows container/server info such as IP, memory, CPU, restarts, status, etc. (`/info`). | `!info` |
|
||
| `!time` | Shows when the container will expire (`/time`). | `!time` |
|
||
| `!root-password` | Requests and returns a new root password (`/rootpass`). | `!root-password` |
|
||
| `!new-api-key` | Generates and returns a new API key (`/new-key`). | `!new-api-key` |
|
||
| `!key-expire-time` | Checks when the current API key will expire (`/key-time`). | `!key-expire-time` |
|
||
| `!x <command>` | Executes a command in the container at the user’s working directory (`/exec`). Allows `cd` usage. | `!x cd /root`, `!x ls -la`, etc. |
|
||
| `!notify <message>` | Sends a custom notification via the API (`/notify`). | `!notify System going offline` |
|
||
|
||
### Special `!x` Sub-Commands (In-Container Navigation)
|
||
|
||
- `!x cd <path>` — Change directory.
|
||
- `!x cd /root` (absolute path)
|
||
- `!x cd ..` (move up one directory)
|
||
- `!x cd ~` (go to `/root`)
|
||
- `!x <any_command>` — Executes `<any_command>` in the current directory of the container.
|
||
|
||
---
|
||
|
||
## Folder Structure
|
||
|
||
```
|
||
linux-teamspeak-bot/
|
||
├── config.json // Your TS3 + API config
|
||
├── tokens.json // Stored user tokens
|
||
├── package.json // Node.js dependencies
|
||
├── teamspeak.js // Main bot code
|
||
└── README.md // This documentation
|
||
``` |