# Welcome Welcome to the documentation of Sonar 2.0, a lightweight anti-bot plugin for Velocity, BungeeCord, and Bukkit. Sonar keeps your server safe from common and even sophisticated bot attacks. ## FAQ **Which Minecraft server software does Sonar support?**\ Sonar supports Velocity, BungeeCord, and Bukkit. You can read more about compatibility [here](/sonar/supported-versions). **On which plugin marketplaces can I find Sonar?**\ You can find Sonar on [Modrinth](https://modrinth.com/plugin/sonar), [Hangar](https://hangar.papermc.io/Jones/sonar), [BuiltByBit](https://builtbybit.com/resources/sonar.23353/?ref=discover), and [SpigotMC](https://www.spigotmc.org/resources/sonar.115239/). It is strongly discouraged to download Sonar from other, potentially untrusted sources. **Which databases are supported for storing verified players?**\ At the moment, Sonar supports [MySQL](https://www.mysql.com/), [MariaDB](https://mariadb.org/), [PostgreSQL](https://www.postgresql.org/), and [H2](https://h2database.com/html/main.html) for storing verified players. **Where can I find the commands and permissions?**\ You can find a list of commands and their respective permissions [here](/administration/commands-and-permissions). **I found a bug! How can I report it?**\ In order to report a bug, you can either open a ticket on [Discord](https://sonar.top/discord), ask for help in the **#help** channel on Discord, or open a [GitHub Issue](https://github.com/jonesdevelopment/sonar/issues/new/choose). **I found a security vulnerability! How can I report it?**\ In order to report a security vulnerability, please visit the [GitHub Security Overview](https://github.com/jonesdevelopment/sonar/security). **What is Sonar 3.0?**\ Sonar 3.0 is a complete recode of Sonar, featuring more advanced checks, much better performance, analytics, a web panel, and priority support. Find out more on our [homepage](https://sonar.top/)! # Getting started Step-by-step guide on how to install Sonar on your server. 1. Download the plugin. 2. Stop your server. 3. Open your server's plugins folder. 4. Drag and drop the Sonar jar file into the plugins folder. 5. Finally, start your server again. That's it! :tada: You can [download the latest stable release](https://github.com/jonesdevelopment/sonar/releases/latest) from the [GitHub repository](https://github.com/jonesdevelopment/sonar/). {% hint style="danger" %} If you are utilizing a proxy (BungeeCord or Velocity), please **refrain from uploading Sonar to every backend server** as Sonar should only be run once for each new connection. {% endhint %} If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) for support. # Supported versions List of all supported Minecraft versions and server software **Client Versions** * **Minecraft: Java Edition** 1.7.2-26.2 * **Minecraft: Bedrock Edition** is handled through [GeyserMC](https://geysermc.org/) (skipped by default; see below) **Software** * Java 17 (or above) **Servers** * [Velocity](https://papermc.io/downloads/velocity) (3.6.0 or above) * [BungeeCord](https://ci.md-5.net/job/BungeeCord/) (1.20 or above) * [Paper](https://papermc.io/downloads/paper) (1.21 or above) * Bukkit/Spigot (1.8.8 or above) * **Bukkit and Spigot are supported**, but it is highly recommended to use Paper. **Dependencies** * [Netty](https://netty.io/) 4.1 (or above) * If your server depends on an older Netty version (1.7.2-1.8.8 servers mainly have this problem), please consider using an updated fork such as [PandaSpigot](https://github.com/hpfxd/PandaSpigot) (or similar alternatives). {% hint style="warning" %} **Disclaimer** * It is possible that some highly altered server forks are unsupported. * Some significantly modified Minecraft clients (including cheats) may interfere with the verification process. Since it is the client developer's duty to guarantee vanilla protocol, this **cannot be fixed by Sonar**. {% endhint %} {% hint style="warning" %} Sonar skips players connecting through GeyserMC by default, as the UDP protocol is deemed unstable, especially when compared to TCP, which Minecraft: Java Edition uses. You can, however, enable support for Bedrock in the configuration. {% endhint %} # Translations Supported languages in Sonar Currently supported languages: * English - by [Jones](https://github.com/jonesdevelopment) - `en` * Dutch - by [Jones](https://github.com/jonesdevelopment) - `nl` * German - by [micartey](https://github.com/micartey) - `de` * Czech - by [slosa](https://github.com/slosacoder) - `cs` * French - by ekiff - `fr` * Turkish - by [Jenkins](https://github.com/ayazjenkins) - `tr` * Polish - by Najek, foren - `pl` * Russian - by MISHA, Null - `ru` * Spanish - by Juansitoh - `es` * Italian - by [Augu0107](https://github.com/Augu0107) - `it` * Indonesian - by [LourenT](https://github.com/LOURENT4462) - `id` * Georgian - by [GreenedDev](https://github.com/GreenedDev), [Chumb3x](https://github.com/chumb3x) - `ka` * Simplified Chinese - by [FallenCrystal](https://github.com/fallencrystal) - `zh` * Brazilian Potuguese - by [RenanGabrieel](https://github.com/RenanGabrieel) - `pt-br` In order to use a language, you need to modify the `language.properties` file in Sonar or change your system language. If you let Sonar regenerate the files (e.g., by deleting them and restarting the server), the new language will be automatically used for the translations. ### Manual migration If you want to manually migrate your language files, you can find all the translated files on GitHub. Simply choose the type of translation (configuration, messages, or webhook configuration) and select the language you want to use in Sonar. Then, you can copy or replace your current file(s) with the file you want to use. If you are interested in contributing new translations, please do so via a GitHub Pull Request. If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) for support. # Commands and Permissions List of all commands, subcommands, and aliases.
CommandAliasesDescription
/sonarNoneList all subcommands and the current version of Sonar
/sonar statistics/sonar statsShow session statistics
/sonar blacklistNoneManage blacklisted IP addresses
/sonar verifiedNoneManage verified IP addresses
/sonar verboseNoneEnable or disable Sonar verbose
/sonar notifyNoneEnable or disable attack notifications
/sonar reloadNoneReload all configurations
/sonar dumpNonePrint developer information
CommandPermissionRestrictions
/sonarsonar.commandNone
/sonar statisticssonar.statisticsNone
/sonar blacklistsonar.blacklistNone
/sonar verifiedsonar.verifiedNone
/sonar verbosesonar.verbosePlayer-only
/sonar notifysonar.notifyPlayer-only
/sonar reloadsonar.reloadNone
/sonar dumpsonar.dumpConsole-only
If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) for support. # MiniMessage Why Sonar uses adventure MiniMessage over legacy color codes Sonar uses [MiniMessage](https://docs.advntr.dev/minimessage/) formatting, as this allows administrators to fully customize all messages to their hearts content. By using MiniMessage in Sonar, administrators are able to use fully custom [colors](https://docs.advntr.dev/minimessage/format.html#color), [click events](https://docs.advntr.dev/minimessage/format.html#click), [hover events](https://docs.advntr.dev/minimessage/format.html#hover), and [more](https://docs.advntr.dev/minimessage/format.html). * You can find a live MiniMessage component preview in the [MiniMessage Viewer](https://webui.advntr.dev/). * You can find Sonar's translations in the `messages.yml` file in the plugin directory. * The MiniMessage formatting does not only apply to chat messages but also to action bars, titles, and disconnect messages. However, some events might not always be supported (for example, you are unable to create a hover or click event in a disconnect message, title, and action bar). If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) for support. # Configuring Sonar ### Quickstart guide The following pages contain useful information that might help with configuring Sonar. 1. [General settings](/administration/configuring-sonar/general-settings) 2. [Adjusting the attack tracker](/administration/configuring-sonar/adjusting-the-attack-tracker) 3. [Setting up a database](/administration/configuring-sonar/setting-up-a-database) 4. [Configuring the verification](/administration/configuring-sonar/configuring-the-verification) 1. [Using 1.20.5+ transfers](/administration/configuring-sonar/configuring-the-verification/using-1.20.5+-transfers) If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) for support. # General settings These settings control general behavior for Sonar, including update checks, logging, and player limits. Enables automatic update checks using the GitHub API to ensure Sonar is up to date. Default: `true` ```yaml check-for-updates: true ``` Determines whether Sonar logs players' IP addresses in the console. Default: `true` ```yaml log-player-addresses: true ``` The number of players allowed to be online with the same IP address. If you have a server where people are allowed to use many alt accounts, you might want to increase this number. Any player who tries joining when there are already more than the maximum number of players using the same IP address online will be kicked. Default: `3` ```yaml max-online-per-ip: 3 ``` # Adjusting the attack tracker The attack tracker in Sonar monitors for potential bot attacks based on player activity. Adjust these settings only if you really know what you're doing. The minimum number of new players required to trigger attack detection. Default: `8` ```yaml min-players-for-attack: 8 ``` The minimum duration (in milliseconds) that an attack must last to be considered ongoing. Default: `30000` ```yaml min-attack-duration: 30000 ``` The minimum number of incident reports needed to confirm an attack, acting as a buffer against false positives. Default: `2` ```yaml min-attack-threshold: 2 ``` The cooldown period (in milliseconds) required before detecting a new attack after one has ended. Default: `3000` ```yaml attack-cooldown-delay: 3000 ``` # Setting up a database Sonar can be connected to a database to retain verified player data even after server restarts. {% hint style="info" %} IP addresses are stored in plain text, so ensure your database is secure. {% endhint %} Defines the type of database used by Sonar. Options include `NONE`, `MYSQL`, `MARIADB`, `POSTGRESQL`, and `H2` (recommended). Default: `NONE` ```yaml type: NONE ``` Specifies the file name for the `H2` database stored in Sonar's plugin directory. Default: `verified_players` ```yaml filename: verified_players ``` The host address for SQL database authentication. Default: `localhost` ```yaml host: localhost ``` The port number for SQL database authentication. Default: `3306` ```yaml port: 3306 ``` The name of the SQL database. Default: `sonar` ```yaml name: sonar ``` The username and password are used by Sonar to authenticate the connection to the database. The connection will fail if no username or password are given. ```yaml username: 'my_username' ``` ```yaml password: 'my_p@ssw0rd!' ``` The number of days Sonar should retain verified players in the database. Default: `5` ```yaml maximum-age: 5 ``` # Configuring the verification These settings control when and how Sonar's bot verification is conducted. Adjust these settings only if you really know what you're doing. Determines when new players are verified. Options: * `ALWAYS`: All new players are checked (Recommended) * `DURING_ATTACK`: Players are only checked during an attack * `NEVER`: No verification for new players Default: `ALWAYS` ```yaml timing: ALWAYS ``` Sets the gamemode during verification. Options: * `SURVIVAL`: all UI components are visible * `CREATIVE`: all UI components are hidden * `ADVENTURE`: all UI components are visible (Recommended) Default: `ADVENTURE` ```yaml gamemode: ADVENTURE ``` Specifies the username used in the cached LoginSuccess packet. Default: `Sonar` ```yaml cached-username: Sonar ``` Logs all new verification attempts. Default: `true` ```yaml log-connections: true ``` Logs verification attempts only during attacks. Default: `false` ```yaml log-during-attack: false ``` Logs all player movements during verification, useful for debugging. Not recommended for production servers. Default: `false` ```yaml debug-xyz-positions: false ``` Enables verification checks for Geyser (Bedrock) players. This is experimental and may cause issues. Default: `true` ```yaml check-geyser-players: true ``` The time (in milliseconds) before disconnecting a player if they stop sending packets. Default: `8000` ```yaml read-timeout: 8000 ``` The time (in milliseconds) before disconnecting a player if the server stops sending packets. Default: `10000` ```yaml write-timeout: 10000 ``` The cooldown period (in milliseconds) before a player can reconnect during verification. Default: `8000` ```yaml rejoin-delay: 8000 ``` The duration (in milliseconds) for which Sonar remembers the number of failed verifications for a player. Default: `120000` ```yaml remember-time: 120000 ``` The duration (in milliseconds) an IP is blocked after repeated verification failures. Default: `600000` ```yaml blacklist-time: 600000 ``` The number of failed verifications before an IP is blacklisted. Set to `0` to disable blacklisting. Default: `2` ```yaml blacklist-threshold: 2 ``` A list of protocol IDs that are blocked from joining the server. Default: `[]` (empty) ```yaml blacklisted-protocols: [] ``` # Using 1.20.5+ transfers Sonar includes a feature that allows players to be automatically transferred back to the origin server after successfully passing bot verification, introduced in Minecraft version 1.20.5. Set to true to enable the transfer feature. **Ensure the feature is enabled in your server's configuration** and **consider adjusting login rate-limiting settings in Velocity or other proxies/plugins to avoid transfer issues**. Default is false. * Set the login ratelimit in Velocity to 1000 (or disable it)—the BungeeCord and Bukkit equivalent is connection throttling. * Enable transfers in velocity.toml (Velocity); config.yml (BungeeCord); server.properties (Bukkit) ```yaml enabled: false ``` Specify the server IP or domain where players should be transferred after verification. This is the IP or domain used by players to connect to your server (e.g., play.my-server.com). ```yaml destination-host: play.my-server.com ``` Define the port for the origin server connection. The default is 25565, which is standard unless your server requires a different port. ```yaml destination-port: 25565 ``` {% hint style="info" %} If your server allows Bedrock players to join via Geyser, make sure to set up [TransferTool](https://github.com/onebeastchris/TransferTool) for Geyser, so Bedrock players are redirected to the correct server. {% endhint %} # Working with the API Brief introduction to Sonar's API and event system Sonar is supposed to be an easy-to-use plugin; therefore, the API has been designed to give a developer almost full control over the behavior of the plugin. ### Using the API Before you are actually able to use the API, you will have to add the dependency to your project. ```gradle maven(url = "https://repo.jonesdev.xyz/releases/") ``` {% hint style="danger" %} Please make sure you do not include the API in your built Jar file by using `compileOnly` instead of `implementation`. {% endhint %} ```gradle compileOnly("xyz.jonesdev.sonar:sonar-api:2.1.46") ``` Now you are able to access all the main API functions by using `Sonar.get()`. Replace `2.1.46` with the version of Sonar you are using. ### Events Using Sonar's built-in event system is also not hard. First, you need to create an event listener: ```java import xyz.jonesdev.sonar.api.event.SonarEvent; import xyz.jonesdev.sonar.api.event.SonarEventListener; import xyz.jonesdev.sonar.api.event.impl.UserVerifySuccessEvent; public final class TestListener implements SonarEventListener { @Override public void handle(final SonarEvent event) { if (event instanceof UserVerifySuccessEvent successEvent) { // ... some example code ... System.out.printf("Test: %s (%s) (took %d ms to verify)%n", successEvent.getUsername(), successEvent.getOfflineUuid(), successEvent.getTimeTakenToVerify()); System.out.println("You can also get the raw user data: " + successEvent.getUser()); } // ... } } ``` Then, you need to register your event listener using the Sonar API: ```java Sonar.get().getEventManager().registerListener(new TestListener()); ``` Have fun developing! # Building Step-by-step guide for building your own version of Sonar. ### Cloning the repository The first step is cloning the repository. You can achieve this by opening your Git terminal in your project folder and typing 
git clone https://github.com/jonesdevelopment/sonar
If you don't want to clone the repository, you can simply download the files as a zip archive. ### Making changes If you want, you can now open your IDE and make some changes to the code. This step is completely optional. ### Building the jar file There are multiple ways of achieving a working jar file for Sonar. If you are using IntelliJ IDEA, you can create a configuration to simplify the building process: 1. Click **Current File** in your project. 2. Click **Edit Configurations.** 3. Add a new **Gradle** configuration. 4. Set the **Run** command to `build-sonar`. 5. Click on **OK** and run the configuration. If you are not using IntelliJ IDEA, you can simply run the Gradle build script itself. * Linux: `./gradlew build-sonar` * Windows: `gradlew.bat build-sonar` {% hint style="info" %} If you are experiencing build failures, try adding `--stacktrace` or `--debug` to your Gradle command. If you have any further questions, please feel free to join the [Discord](https://sonar.top/discord) and ask for help. {% endhint %} # Guidelines ### Contributing Guidelines 1. Fork the repository and create a new branch for your contribution. 2. Follow the coding guidelines for your code. 3. Test your code before committing and pushing it. 4. Use [semantic](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716) commit messages for your commits. ### Coding Guidelines * Use the same code style and formatting as the rest of the project. * Optional: Use an IDE that supports `.editorconfig` files. * Use meaningful names for variables, classes, and methods. * Write clear comments to explain complex parts of your code. * Ensure your code is easy to read and maintain. # Pull Requests Step-by-step guide on how to open a pull request. Before opening a pull request, you will need to create a fork of the GitHub repository. Furthermore, you can follow the [Building guide](broken://pages/FE8pTQ5Q89iCidc2yT0D) and add your own patches or features. Please make sure that no one else has already opened a pull request with the exact same patches or features. ### Guidelines Please make sure to read the [Contributing Guidelines](/contributing/guidelines). ### GitHub pull requests Once your changes are made, open a pull request: 1. Navigate to your forked Sonar repository. 2. Click the **New pull request** button. 3. Use a clear and descriptive title for your pull request. 4. Provide a detailed description of the changes you made. 5. Reference related issues or pull requests. 6. Make sure everything is properly tested. 7. Open the pull request and wait for feedback. # Bug Reports Step-by-step guide on how to report a bug (or other issue). ### Guidelines 1. Check if someone has already reported the bug. 2. If not, open a new issue with a clear and detailed title. 3. Describe the bug, including the steps to reproduce it. 4. Include all logs related to the issue. 5. Provide the output of '/sonar dump'. 6. Feel free to provide any additional information. Please make sure to read the [Contributing Guidelines](/contributing/guidelines). ### Discord Ticket You can report a bug on Discord by opening a ticket: 1. Join the [Discord](https://sonar.top/discord). 2. Go to the `open-ticket` text channel. 3. Click on **Create Ticket**. 4. Navigate to the newly created channel. 5. Explain the issue and provide examples. 6. Provide the output of `/sonar dump` (from the console). 7. Provide log files if there are any errors. 8. Feel free to add screenshots or other additional information. ### GitHub issue tracker If you want to use GitHub's issue tracker, you can simply visit the GitHub repository and create a new Issue: 1. Click on **Issues** followed by **New Issue**. 2. Select your issue type (e.g., **Bug Report**) by clicking on **Get started**. 3. Fill out the form. 4. Provide log files if there are any errors. 5. Feel free to add screenshots or other additional information. # Feature Requests Step-by-step guide on how to request a feature. Requesting a feature is as simple as reporting a bug. You can either open a GitHub issue or ask on Discord. ### Guidelines 1. Check if someone has already made the same request. 2. If not, open a new issue with a clear and detailed title. 3. Explain the feature you want to see in Sonar and provide an example. 4. Explain why you want to see the feature in Sonar. 5. Feel free to provide any additional information. Please make sure to read the [Contributing Guidelines](/contributing/guidelines). ### GitHub issue tracker If you want to use GitHub's issue tracker, you can simply visit the GitHub repository and create a new Issue: * Click on **Issues** followed by **New Issue**. * Select your issue type (e.g., **Feature Request**) by clicking on **Get started**. * Fill out the form. * Feel free to add screenshots or other additional information.