From 2be048462121f2e8c1bf8a839e7370070b6bdac3 Mon Sep 17 00:00:00 2001 From: Leigh MacDonald Date: Fri, 14 Jun 2024 01:41:53 -0600 Subject: [PATCH] Add ban and moderation info. --- docs/docs/devel/STATS.md | 28 ---------- docs/docs/devel/{BUILD.md => build.md} | 4 +- docs/docs/devel/{DEVEL.md => devel.md} | 0 docs/docs/devel/{DOCS.md => docs.md} | 0 docs/docs/guide/DATABASE.md | 19 ------- docs/docs/guide/bans.md | 54 ++++++++++++++++++++ docs/docs/guide/{DISCORD.md => discord.md} | 2 +- docs/docs/guide/moderation.md | 2 + docs/docs/guide/sourcemod.md | 50 ++++++++++++++++++ docs/docs/guide/stats.md | 25 +++++++++ docs/docs/install/{CONFIG.md => config.md} | 9 +--- docs/docs/install/{INSTALL.md => install.md} | 0 docs/docs/{INTRO.md => intro.md} | 6 +-- sourcemod/scripting/gbans.sp | 4 +- 14 files changed, 139 insertions(+), 64 deletions(-) delete mode 100644 docs/docs/devel/STATS.md rename docs/docs/devel/{BUILD.md => build.md} (88%) rename docs/docs/devel/{DEVEL.md => devel.md} (100%) rename docs/docs/devel/{DOCS.md => docs.md} (100%) delete mode 100644 docs/docs/guide/DATABASE.md create mode 100644 docs/docs/guide/bans.md rename docs/docs/guide/{DISCORD.md => discord.md} (99%) create mode 100644 docs/docs/guide/moderation.md create mode 100644 docs/docs/guide/sourcemod.md create mode 100644 docs/docs/guide/stats.md rename docs/docs/install/{CONFIG.md => config.md} (94%) rename docs/docs/install/{INSTALL.md => install.md} (100%) rename docs/docs/{INTRO.md => intro.md} (71%) diff --git a/docs/docs/devel/STATS.md b/docs/docs/devel/STATS.md deleted file mode 100644 index 2efcf9ad5..000000000 --- a/docs/docs/devel/STATS.md +++ /dev/null @@ -1,28 +0,0 @@ -# Stats Overview - -Stats are generated for many game events. They are summarized into atomic matches and stores in the database. The -design goal is to have a cross between [logs.tf](https://logs.tf) -and [hlstatsx:ce](https://github.com/A1mDev/hlstatsx-community-edition). - -## Compared with hlstatsx:ce - -- Simpler deployments, single monolithic binary. -- Considerably better scaling performance: - - Stats are summarized in real time in memory into a `Match` instance - - Matches are committed to the database in a single transaction instead of immediately upon incoming events -- Long term tracking of who killed who is not available currently - -## General Info - -- Ignores showing stats from players in the match < 60 seconds -- Matches that dont have a minimum amount of players are discarded -- Matches are - -## Incoming Events Flow - -1. gbans udp log listener starts -2. Incoming logs get parsed with the [logparse.LogParser](pkg/logparse/log_parser.go) pkg. -3. If a match does not exist, create a new [logparse.Match](pkg/logparse/match.go) to feed parsed events into for - summarizing -4. Get game over event, save match to database. -5. Broadcast match result summary to discord diff --git a/docs/docs/devel/BUILD.md b/docs/docs/devel/build.md similarity index 88% rename from docs/docs/devel/BUILD.md rename to docs/docs/devel/build.md index 200e497b5..3099c2e1c 100644 --- a/docs/docs/devel/BUILD.md +++ b/docs/docs/devel/build.md @@ -14,9 +14,7 @@ the project into distinct sentry projects. ### Backend -After creating your backend project you can copy and paste the url shown into `gbans.yml` -under the `logging.sentry_dsn` key. No further configuration should be required. - +TODO ### Frontend diff --git a/docs/docs/devel/DEVEL.md b/docs/docs/devel/devel.md similarity index 100% rename from docs/docs/devel/DEVEL.md rename to docs/docs/devel/devel.md diff --git a/docs/docs/devel/DOCS.md b/docs/docs/devel/docs.md similarity index 100% rename from docs/docs/devel/DOCS.md rename to docs/docs/devel/docs.md diff --git a/docs/docs/guide/DATABASE.md b/docs/docs/guide/DATABASE.md deleted file mode 100644 index 02acc6923..000000000 --- a/docs/docs/guide/DATABASE.md +++ /dev/null @@ -1,19 +0,0 @@ -# Database Reference - -## Creating a sourcemod user - -It's recommended to create a secondary non-privileged user, especially when using servers remote of the -gbans instance. Below is an example of creating a read-only user that only has access to the tables, and functions, required -for operation. - -```postgresql -CREATE ROLE sourcemod WITH LOGIN PASSWORD ''; -GRANT CONNECT ON DATABASE gbans TO sourcemod; -GRANT USAGE ON SCHEMA public TO sourcemod ; -GRANT SELECT ON - sm_config, sm_overrides, sm_group_overrides, sm_group_immunity, sm_groups, - sm_admins_groups, sm_adminsTO sourcemod; -GRANT SELECT, INSERT, UPDATE, DELETE ON sm_cookie_cache, sm_cookies TO sourcemod; -GRANT EXECUTE ON FUNCTION check_ban TO sourcemod; - -``` diff --git a/docs/docs/guide/bans.md b/docs/docs/guide/bans.md new file mode 100644 index 000000000..c9fee59b8 --- /dev/null +++ b/docs/docs/guide/bans.md @@ -0,0 +1,54 @@ +# Ban functionality + +This page outlines the various methods players can be banned. Currently, it's only possible to appeal +a steam ban. The rest are considered effectively permanent. + +## Steam Bans + +The standard ban usecase, banning by steam ID. Note the 2 special options for `Include Friends` and `IP Evading Allowed`. + +If include friends is enabled, then all the ban recipients friends will also be banned. Friends do not receive a entry +in the ban table however, and are automatically allowed back once the parents ban is completed. The list of friends is only +updated periodically, so you may have to wait several hours for the changes to take effect and existing banned friends get +flushed. + +IP evasion option allows users to connect from the same ip as a currently banned user. When not enabled, users +are automatically banned for `evasion` and their ban lengths are changed to permanent. If you want a banned users "brother" +to be able to play, then be sure to enable this. + +This type of ban is the only one that allows `muting` players. + +## CIDR bans + +Similar to steam bans, except they also match against a [cidr](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) range. + +For example, to ban a user and his entire network block, you could ban `50.60.70.0/24`. This would ban anyone connecting +from `50.60.70.0 - 50.60.70.255`. + +## ASN Bans + +[ANS](https://en.wikipedia.org/wiki/Autonomous_system_(Internet)) bans are probably the least used option. They should +be used with care as they can be too broad in what they ban if you are not careful. If a user connects with a range that +the banned ASN owns, the user will be kicked. + + +## Steam Group Bans + +Ban all members of a particular steam group from connecting. + +You can find a groups GID by opening the memberslist directly. You can achieve this by appending `/memberslistxml/?xml=1` +to the url of the steam group. You should end up with something like: + + https://steamcommunity.com/groups/valve/memberslistxml/?xml=1 + +Inside here, at the top, you should see the group ID you can use for banning: + +```xml +103582791429521412 +``` + +Similar to the friends list bans, these are also updated periodically. Any changes may take a few hours to flush +through the system. + +Valve does not like hitting the memberslist endpoint that often without getting rate limited. Currently there is no +protections for this, so its advised to not add too many entries for now. \ No newline at end of file diff --git a/docs/docs/guide/DISCORD.md b/docs/docs/guide/discord.md similarity index 99% rename from docs/docs/guide/DISCORD.md rename to docs/docs/guide/discord.md index 507a0aaa0..2b1129a11 100644 --- a/docs/docs/guide/DISCORD.md +++ b/docs/docs/guide/discord.md @@ -2,7 +2,7 @@ Here you will find an outline of the various available discord bot commands you can use. -This of course assumes you have discord integration enabled. See [INSTALL.md](../install/INSTALL.md) for details on +This of course assumes you have discord integration enabled. See [INSTALL.md](../install/install) for details on how to enable it. ## Overview diff --git a/docs/docs/guide/moderation.md b/docs/docs/guide/moderation.md new file mode 100644 index 000000000..86cf3ba59 --- /dev/null +++ b/docs/docs/guide/moderation.md @@ -0,0 +1,2 @@ +# Moderation + diff --git a/docs/docs/guide/sourcemod.md b/docs/docs/guide/sourcemod.md new file mode 100644 index 000000000..f9b307981 --- /dev/null +++ b/docs/docs/guide/sourcemod.md @@ -0,0 +1,50 @@ +# Sourcemod Plugin + +This covers functionality available through the gbans plugin as well as some recommended configuration options. + +## In-Game Commands + +| Command | Perms | Description | +|------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| gb_mod | | Sends a notification to discord (if its enabled) to the users belonging to the group configured in the "mod ping role id" discord setting. | +| gb_ban | ADMFLAG_BAN | Ban a user using in-game menu. | +| gb_reload | ADMFLAG_ROOT | Reinitializes some parts of the plugin such as authentication password. | +| gb_version | | Shows the current plugin version. | +| report | | Report a user. | + +## Convars + +| convar | default value | Description | +|----------------------|--------------------|---------------------------------------------------------| +| gb_core_host | localhost | Address gbans is listening on | +| gb_core_port | 6006 | Port gbans is listening on | +| gb_core_server_key | '' | Password generated by gbans to authenticate the server. | +| gb_disable_autoteam | 1 | Disallow the use of the autoteam command | +| gb_hide_connections | 1 | Dont show the connect/disconnect message to users | +| gb_stv_enable | 1 | Enable SourceTV | +| gb_auto_record | 1 | Enable automatic recording | +| gb_stv_minplayers | 1 | Minimum players on server to start recording | +| gb_stv_ignorebots | 1 | Ignore bots in the player count | +| gb_stv_timestart | -1 | Hour in the day to start recording (0-23, -1 disables) | +| gb_stv_timestop | -1 | Hour in the day to stop recording (0-23, -1 disables) | +| gb_stv_finishmap | 1 | If 1, continue recording until the map ends | +| gb_stv_path | stv_demos/active | Path to store currently recording demos | +| gb_stv_path_complete | stv_demos/complete | Path to store complete demos | + +## Creating a sourcemod database user + +It's recommended to create a secondary less-privileged user, especially when using servers remote of the +gbans instance. Below is an example of creating a restricted user that only has access to the tables, and functions, required +for operation. + +```postgresql +CREATE ROLE sourcemod WITH LOGIN PASSWORD ''; +GRANT CONNECT ON DATABASE gbans TO sourcemod; +GRANT USAGE ON SCHEMA public TO sourcemod ; +GRANT SELECT ON + sm_config, sm_overrides, sm_group_overrides, sm_group_immunity, sm_groups, + sm_admins_groups, sm_admins TO sourcemod; +GRANT SELECT, INSERT, UPDATE, DELETE ON sm_cookie_cache, sm_cookies TO sourcemod; +GRANT EXECUTE ON FUNCTION check_ban TO sourcemod; + +``` diff --git a/docs/docs/guide/stats.md b/docs/docs/guide/stats.md new file mode 100644 index 000000000..fb76c1720 --- /dev/null +++ b/docs/docs/guide/stats.md @@ -0,0 +1,25 @@ +# Stats Overview + +Stats are generated for many game events. They are summarized into atomic matches and stores in the database. The +design goal is to have a cross between [logs.tf](https://logs.tf) +and [hlstatsx:ce](https://github.com/A1mDev/hlstatsx-community-edition). + +## Compared with hlstatsx:ce + +- Simpler deployments, single monolithic binary. +- Considerably better scaling performance +- Matches are committed to the database in a single transaction instead of immediately upon incoming events +- Long term tracking of who killed who is not available currently + +## General Info + +- Ignores showing stats from players in the match < 60 seconds +- Matches that dont have a minimum amount of players are discarded +- Matches are + +## How stats are generated (new, WIP) + +1. gbans checks for new demos. +2. If a demo exists, download it locally or stop. +3. Demo is uploaded to the [parsing service](https://github.com/leighmacdonald/tf2_demostats) (avail soon). +4. Results are inserted into the database. \ No newline at end of file diff --git a/docs/docs/install/CONFIG.md b/docs/docs/install/config.md similarity index 94% rename from docs/docs/install/CONFIG.md rename to docs/docs/install/config.md index 8c268b8b5..beea267b8 100644 --- a/docs/docs/install/CONFIG.md +++ b/docs/docs/install/config.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# Config +# Base Configuration ## Server @@ -65,13 +65,6 @@ This config file should be places in `tf/addons/sourcemod/configs/gbans.cfg`. The server gbans server is running you should now be able to see the `[GB]` message logs in the console. With a message like below on successful authentication with the server. -``` -[GB] Using config file: addons/sourcemod/configs/gbans.cfg -[GB] Request to https://gbans.example.com/v1/auth finished with status code 200 in 0.01 seconds -[GB] Successfully authenticated with gbans server - -``` - ## Discord To use discord you need to [create a discord application](https://discord.com/developers/applications). You will need diff --git a/docs/docs/install/INSTALL.md b/docs/docs/install/install.md similarity index 100% rename from docs/docs/install/INSTALL.md rename to docs/docs/install/install.md diff --git a/docs/docs/INTRO.md b/docs/docs/intro.md similarity index 71% rename from docs/docs/INTRO.md rename to docs/docs/intro.md index a29662059..db19fe380 100644 --- a/docs/docs/INTRO.md +++ b/docs/docs/intro.md @@ -26,12 +26,12 @@ in golang, typescript and sourcepawn and consists of 3 major components: - Flagging and automatic action for flagged words - Sourcemod SQL Admins compatibility -Most of these features have some level of being toggled on/off. +Most of these features have some level of being toggled on/off so you can choose what features suits your setup best. ## Installation Guide -To get started with installation, please see the [installation guide](./install) +To get started with installation, please see the [installation](./install) guide. ## Development Guide -If you want to hack on gbans, please see the [devel](./devel) section to get started. \ No newline at end of file +If you want to hack on gbans, please see the [develelopment](./devel) guide to get started. \ No newline at end of file diff --git a/sourcemod/scripting/gbans.sp b/sourcemod/scripting/gbans.sp index d5046090a..6a93b37f5 100644 --- a/sourcemod/scripting/gbans.sp +++ b/sourcemod/scripting/gbans.sp @@ -65,8 +65,8 @@ public void OnPluginStart() gb_core_server_key = AutoExecConfig_CreateConVar("gb_core_server_key", "", "GBans server key used to authenticate with the service", FCVAR_NONE); // In Game Tweaks - gb_disable_autoteam = AutoExecConfig_CreateConVar("gb_hide_connections", "1", "Dont show the disconnect message to users", FCVAR_NONE, true, 0.0, true, 1.0); - gb_hide_connections = AutoExecConfig_CreateConVar("gb_disable_autoteam", "1", "Dont allow the use of autoteam command", FCVAR_NONE, true, 0.0, true, 1.0); + gb_disable_autoteam = AutoExecConfig_CreateConVar("gb_hide_connections", "1", "Dont allow the use of autoteam command", FCVAR_NONE, true, 0.0, true, 1.0); + gb_hide_connections = AutoExecConfig_CreateConVar("gb_disable_autoteam", "1", "Dont show the disconnect message to users", FCVAR_NONE, true, 0.0, true, 1.0); // STV settings gb_stv_enable = AutoExecConfig_CreateConVar("gb_stv_enable", "1", "Enable SourceTV", FCVAR_NONE, true, 0.0, true, 1.0);