From 0e44fa10f7521c296163ef7d81ed3fb49189c62f Mon Sep 17 00:00:00 2001 From: Chase Hall Date: Thu, 6 Aug 2020 13:20:35 -0500 Subject: [PATCH] Consolidate README (#156) * Consolidate README. We use the wiki now for most information, this just reduces "duplicate" data. --- README.md | 422 +----------------------------------------------------- 1 file changed, 2 insertions(+), 420 deletions(-) diff --git a/README.md b/README.md index 839d6ea6..d3d654a5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -# IW4MAdmin +# IW4MAdmin [![GitHub license](https://img.shields.io/github/license/RaidMax/IW4M-Admin)](https://github.com/RaidMax/IW4M-Admin/blob/2.4-pr/LICENSE) [![GitHub stars](https://img.shields.io/github/stars/RaidMax/IW4M-Admin)](https://github.com/RaidMax/IW4M-Admin/stargazers) ### Quick Start Guide -### Version 2.4 _______ ### About **IW4MAdmin** is an administration tool for [IW4x](https://iw4x.org/), [Pluto T6](https://forum.plutonium.pw/category/6/plutonium-t6), [Pluto IW5](https://forum.plutonium.pw/category/14/plutonium-iw5), [CoD4x](https://cod4x.me/), [TeknoMW3](https://github.com/Musta1337/TeknoMW3), and most Call of Duty® dedicated servers. It allows complete control of your server; from changing maps, to banning players, **IW4MAdmin** monitors and records activity on your server(s). With plugin support, extending its functionality is a breeze. @@ -45,424 +44,7 @@ Linux ### Help Feel free to join the **IW4MAdmin** [Discord](https://discord.gg/ZZFK5p3) If you come across an issue, bug, or feature request please post an [issue](https://github.com/RaidMax/IW4M-Admin/issues) -___ - -### Configuration -#### Initial Configuration -When **IW4MAdmin** is launched for the _first time_, you will be prompted to setup your configuration. - -`Enable webfront` -* Enables you to monitor and control your server(s) through a web interface -* Default — `http://0.0.0.0:1624` - -`Enable multiple owners` -* Enables more than one client to be promoted to level of `Owner` -* Default — `false` - -`Enable stepped privilege hierarchy` -* Allows privileged clients to promote other clients to the level below their current level -* Default — `false` - -`Enable custom say name` -* Shows a prefix to every message send by **IW4MAdmin** -- `[Admin] message` -* _This feature requires you specify a custom say name_ -* _This feature only works on games that support the `sv_sayName` dvar_ -* Default — `false` - -`Enable social link` -* Shows a link to your community's social media/website on the webfront -* Default — `false` - -`Use Custom Encoding Parser` -* Allows alternative encodings to be used for parsing game information and events -* **Russian users should use this and then specify** `windows-1251` **as the encoding string** -* Default — `false` - -#### Server Configuration -After initial configuration is finished, you will be prompted to configure your servers for **IW4MAdmin**. - -`Enter server IP Address` -* For almost all scenarios `127.0.0.1` is sufficient -* Default — `n/a` - -`Enter server port` -* The port that your server is listening on (can be obtained via `net_port`) -* Default — `n/a` - -`Enter server RCon password` -* The *\(R\)emote (Con)sole* password set in your server configuration (can be obtained via `rcon_password`) -* Default — `n/a` - -`Enter number of reserved slots` -* The number of client slots reserved for privileged players (unavailable for regular users to occupy) -* For example, if you enter **2** reserved slots on an **18** slot server, you will have **16** publicly available slots -* Default — `0` - -#### Advanced Configuration -If you wish to further customize your experience of **IW4MAdmin**, the following configuration file(s) will allow you to changes core options using any text-editor. - -#### `IW4MAdminSettings.json`-- this file is created after initial setup -* This file uses the [JSON](https://en.wikipedia.org/wiki/JSON#JSON_sample) specification, so please validate your configuration before running **IW4MAdmin** - -`ManualWebfrontUrl` -* Specifies the webfront URL. -* The value can be an [IP Address](https://en.wikipedia.org/wiki/IP_address):port or [Domain Name](https://en.wikipedia.org/wiki/Domain_name):port -* Example http://gameserver.com:8080 -* Useful for things like [YADB](https://forum.awog.at/topic/89/release-yadb-yet-another-discord-bridge) as it will use that URL instead of the IP address. -* Default — `null` - -`WebfrontBindUrl` -* Specifies the address and port the webfront will listen on. -* The value can be an [IP Address](https://en.wikipedia.org/wiki/IP_address):port or [Domain Name](https://en.wikipedia.org/wiki/Domain_name):port -* Example http://gameserver.com:8080 -* Default — `http://0.0.0.0:1624` (indicates that it will listen on all IP Addresses available to the default interface) - -`CustomLocale` -* Specifies a [locale name](https://msdn.microsoft.com/en-us/library/39cwe7zf.aspx) to use instead of system default -* Locale must be from the `Equivalent Locale Name` column -* Default — `windows-1252` - -`ConnectionString` -* Specifies the [connection string](https://www.connectionstrings.com/mysql/) to a MySQL server that is used instead of SQLite -* Default — `null` - -`DatabaseProvider` -* Specifies the database provider **IW4MAdmin** should use -* Possible values — `sqlite`, `mysql`, `postgresql` -* Default — `sqlite` - -`Ignore Bots` -* Disables bots from being registered and tracked by **IW4MAdmin** - -`RConPollRate` -* Specifies (in milliseconds) how often to poll each server for updates -* Default — `5000` - -`Servers` -* Specifies the list of servers **IW4MAdmin** will monitor -* Default — `[]` -* `IPAddress` - * Specifies the IP Address of the particular server - * Default — `n/a` -* `Port` - * Specifies the port of the particular server - * Default — `n/a` -* `Password` - * Specifies the `rcon_password` of the particular server - * Default — `n/a` -* `ManualLogPath` - * Specifies the log path to be used instead of the automatically generated one - * To use the `GameLogServer`, this should be set to the http address that the `GameLogServer` is listening on - * Example — http://gamelogserver.com/ - * Default — `null` -* `AutoMessages` - * Specifies the list of messages that are broadcasted to the particular server - * Default — `[]` -* `Rules` - * Specifies the list of rules that apply to the particular server - * Default — `[]` -* `ReservedSlotNumber` - * Specifies the number of client slots to reserve for privileged users - * Default — `0` -* `GameLogServerUrl` - * Specifies the HTTP Url for the Game Log Server - * Default — `null` - -`AutoMessagePeriod` -* Specifies (in seconds) how often messages should be broadcasted to each server -* Default — `60` - -`AutoMessages` -* Specifies the list of messages that are broadcasted to **all** servers -* Specially formatted **tokens** can be used to broadcast dynamic information -* `{{TOTALPLAYERS}}` — displays how many players have connected -* `{{TOPSTATS}}` — displays the top 5 players on the server based on performance -* `{{MOSTPLAYED}}` — displays the top 5 players based on number of kills -* `{{TOTALPLAYTIME}}` — displays the cumulative play time (in man-hours) on all monitored servers -* `{{VERSION}}` — displays the version of **IW4MAdmin** -* `{{ADMINS}}` — displays the currently connected and *unmasked* privileged users online -* `{{NEXTMAP}}` — displays the next map and gametype in rotation - -`GlobalRules` -* Specifies the list of rules that apply to **all** servers` - -`Maps` -* Specifies the list of maps for each supported game -* `Name` - * Specifies the name of the map as returned by the game (usually the file name sans the file extension) -* `Alias` - * Specifies the display name of the map (as seen while loading in) -___ - -### Commands -|Name |Alias|Description |Requires Target|Syntax |Required Level| -|--------------| -----| --------------------------------------------------------| -----------------| -------------| ---------------| -|prune|pa|demote any trusted clients that have not connected recently (defaults to 30 days)|False|!pa \|Owner| -|quit|q|quit IW4MAdmin|False|!q |Owner| -|rcon|rcon|send rcon command to server|False|!rcon \|Owner| -|ban|b|permanently ban a client from the server|True|!b \ \|SeniorAdmin| -|unban|ub|unban client by client id|True|!ub \ \|SeniorAdmin| -|find|f|find client in database|False|!f \|Administrator| -|killserver|kill|kill the game server|False|!kill |Administrator| -|map|m|change to specified map|False|!m \|Administrator| -|maprotate|mr|cycle to the next map in rotation|False|!mr |Administrator| -|plugins|p|view all loaded plugins|False|!p |Administrator| -|tempban|tb|temporarily ban a client for specified time (defaults to 1 hour)|True|!tb \ \ \|Administrator| -|alias|known|get past aliases and ips of a client|True|!known \|Moderator| -|baninfo|bi|get information about a ban for a client|True|!bi \|Moderator| -|fastrestart|fr|fast restart current map|False|!fr |Moderator| -|flag|fp|flag a suspicious client and announce to admins on join|True|!fp \ \|Moderator| -|kick|k|kick a client by name|True|!k \ \|Moderator| -|list|l|list active clients|False|!l |Moderator| -|mask|hide|hide your presence as a privileged client|False|!hide |Moderator| -|reports|reps|get or clear recent reports|False|!reps \|Moderator| -|say|s|broadcast message to all clients|False|!s \|Moderator| -|setlevel|sl|set client to specified privilege level|True|!sl \ \|Moderator| -|setpassword|sp|set your authentication password|False|!sp \|Moderator| -|unflag|uf|Remove flag for client|True|!uf \|Moderator| -|uptime|up|get current application running time|False|!up |Moderator| -|usage|us|get application memory usage|False|!us |Moderator| -|warn|w|warn client for infringing rules|True|!w \ \|Trusted| -|warnclear|wc|remove all warnings for a client|True|!wc \|Trusted| -|admins|a|list currently connected privileged clients|False|!a |User| -|getexternalip|ip|view your external IP address|False|!ip |User| -|help|h|list all available commands|False|!h \|User| -|nextmap|nm|view next map in rotation|False|!nm |User| -|owner|iamgod|claim ownership of the server|False|!iamgod |User| -|ping|pi|get client's latency|False|!pi \|User| -|privatemessage|pm|send message to other client|True|!pm \ \|User| -|report|rep|report a client for suspicious behavior|True|!rep \ \|User| -|rules|r|list server rules|False|!r |User| -|setgravatar|sg|set gravatar for webfront profile|False|!sg \|User| -|whoami|who|give information about yourself|False|!who |User| - - -_These commands include all shipped plugin commands._ --- -#### Player Identification -All players are identified 5 separate ways -1. `npID/GUID/XUID` - The ID corresponding to the player's hardware or forum account -2. `IP` - The player's IP Address -3. `Client ID` - The internal reference to a player, generated by **IW4MAdmin** -4. `Name` - The visible player name as it appears in game -5. `Client Number` - The slot the client occupies on a server. (The number ranges between 0 and the max number of clients allowed on the server) - -For most commands players are identified by their `Name` -However, if they are currently offline, or their name contains un-typable characters, their `Client ID` must be used - -The `Client ID` is specified by prefixing a player's reference number with `@`. -For example, `@123` would reference the player with a `Client ID` of 123. - -**All commands that require a `target` look at the `first argument` for a form of player identification** - ---- - -#### Additional Command Examples -`setlevel` -- _shortcut_ - `sl` -- _Parameter 1_ - Player to modify level of -- _Parameter 2_ - Level to set the player to ```[ User, Trusted, Moderator, Administrator, SeniorAdmin, Owner ]``` -- _Example_ - `!setlevel Player1 SeniorAdmin`, `!sl @123 Moderator` -- **NOTE** - An `owner` cannot set another player's level to `owner` unless the configuration option is enabled during setup - -`ban` -- _Shortcut_ - `b` -- _Parameter 1_ - Player to ban -- _Parameter 2_ - Reason for ban -- _Example_ - `!ban Player1 caught cheating`, `!b @123 GUID Spoofing` - -`tempban` -- _Shortcut_ - `tb` -- _Parameter 1_ - Player to ban -- _Parameter 2_ - Ban length (minutes|hours|days|weeks|years) -- _Parameter 3_ - Reason for ban -- _Example_ - `!tempban Player1 3w racism`, `!tb @123 8h Abusive behaivor` - -`reports` -- _Shortcut_ - `reps` -- _Optional Parameter 1_ - `clear` (erases reports for current server) - -___ -### Plugins - -#### Welcome -- This plugin uses geo-location data to welcome a player based on their country of origin -- All privileged users ( Trusted or higher ) receive a specialized welcome message as well -- Welcome messages can be customized in `WelcomePluginSettings.json` - -#### Stats -- This plugin calculates basic player performance, skill approximation, and kill/death ratio -- Skill is an number derived from an algorithmic processing of a player's Kill Death Ratio (KDR) and Score per Minute (SPM). -- Elo Rating is based off of the number of encounters a player wins. -- Performance is the average of Skill + Elo Rating - -**Commands added by this plugin** - -|Name |Alias|Description |Requires Target|Syntax |Required Level| -|--------------| -----| --------------------------------------------------------| -----------------| -------------| ----------------| -|resetstats|rs|reset your stats to factory-new|False|!rs |User| -|stats|xlrstats|view your stats|False|!xlrstats \|User| -|topstats|ts|view the top 5 players on this server|False|!ts |User| -|mostplayed|mp|view the top 5 dedicated players on the server|False|!mp |User| - -- To qualify for top stats, a client must have played for at least `3 hours` and connected within the past `15 days`. - -#### Login -- This plugin deters GUID spoofing by requiring privileged users to login with their password before executing commands -- A password must be set using the `setpassword` command before logging in - - **Commands added by this plugin** - -|Name |Alias|Description |Requires Target|Syntax |Required Level| -|--------------| -----| --------------------------------------------------------| -----------------| -------------| ----------------| -|login|l|login using password|False|!l \|Trusted| - -#### Profanity Determent -- This plugin warns and kicks players for using profanity -- Profane words and warning message can be specified in `ProfanityDetermentSettings.json` -- If a client's name contains a word listed in the settings, they will immediately be kicked - -#### IW4 Script Commands -- This plugin provides additional integration to IW4x -- In order to take advantage of it, copy the `userraw` folder into your IW4x server directory - -#### VPN Detection [Script Plugin] -- This plugin detects if a client is using a VPN and kicks them if they are -- To disable this plugin, delete `Plugins\VPNDetection.js` -- Adding **Client IDs** to the `vpnExceptionIds` array will prevent a client from being kicked. - -#### Shared GUID Kicker [Script Plugin] -- This plugin kicks users using a specific GUID -- GUID `F4D2C30B712AC6E3` on IW4x was packed into a torrent version of the game. -___ -### Webfront -`Home` -* Shows an overview of the monitored server(s) - -`Penalties` -* Shows a chronological ordered list of client penalties (scrolling down loads older penalties) - -`Admins` -* Shows a list of privileged clients - -`Login` -* Allows privileged users to login using their `Client ID` and password set via `setpassword` -* `ClientID` is a number that can be found by using `!find ` or find the client on the webfront and copy the ID following `ProfileAsync/` - -`Profile` -* Shows a client's information and history - -`Web Console` -* Allows logged in privileged users to execute commands as if they are in- - -`Search` -* Query clients and messages - -Advanced filters can be constructed to search for resources using the following filter table. -| Filter | Description | Format | Example | -|-----------|--------------------------------------------------------|-----------------------|---------------------| -| before | include items occurring on or before the provided date | YYYY-MM-DD hh:mm:ss (UTC inferred) | 2020-05-21 23:00:00 | -| after | include items occurring on or after the provided date | YYYY-MM-DD hh:mm:ss (UTC inferred) | 2015-01-01 | -| server | include items matching the server id | ip:port | 127.0.0.1:28960 | -| client | include items matching the client id | integer | 8947 | -| contains | include items containing this substring | string | hack | -| sort | display results in this order | ascending\|descending | descending | - -Any number of filters can be combined in any order. -Example — `chat|before 2020-05-21|after 2020-05-01|server 127.0.0.1:28960|client 444|contains cheating|sort descending` - ---- -### Game Log Server -The game log server provides a way to remotely host your server's log over a http rest-ful api. -This feature is useful if you plan on running IW4MAdmin on a different machine than the game server. -#### Requirements -- [Python 3.8.x](https://www.python.org/downloads/) or newer - -#### Installation -1. With Python 3.x installed, open up a terminal/command prompt window in the `GameLogServer` folder and execute: - ```console - pip install -r requirements.txt - ``` - If this fails, you can alternatively try installing with: - ```console - python -m pip install -r requirements.txt - ``` -2. Allow TCP port 1625 through firewall - * [Windows Instructions](https://www.tomshardware.com/news/how-to-open-firewall-ports-in-windows-10,36451.html) - * [Linux Instructions (iptables)](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-basic-iptables-firewall-on-centos-6#open-up-ports-for-selected-services) -#### Launching -With Python 3 installed, open a terminal/command prompt window open in the `GameServerLog` folder and execute: -```console -python runserver.py -``` -The Game Log Server window will need to remain running/open as long as **IW4MAdmin** is running - -#### Configuring -* Update your `IW4MAdminSettings.json` by changing the value of `GameLogServerUrl` to "http://:1625" -* Example — `"GameLogServerUrl": "http://192.168.1.123:1625",` ---- -### Extending Plugins - -#### NuGet Package -The NuGet package for **IW4MAdmin's** "Shared Library" can be obtained from the [NuGet Gallery](https://www.nuget.org/packages/RaidMax.IW4MAdmin.SharedLibraryCore) -Referencing this package will give you the ability to write plugins against **IW4MAdmin's** core library. -#### Code -**IW4MAdmin's** functionality can be extended by writing additional plugins in C#. -Each class library must implement the `IPlugin` interface. -See the existing [plugins](https://github.com/RaidMax/IW4M-Admin/tree/master/Plugins) for examples. -#### JavaScript -**IW4MAdmin** functionality can also be extended using JavaScript. -The JavaScript parser supports [ECMA 5.1](https://ecma-international.org/ecma-262/5.1/) standards. -#### Plugin Object Template -In order to be properly parsed by the JavaScript engine, every plugin must conform to the following template. -```js -var plugin = { - author: 'YourHandle', - version: 1.0, - name: 'Sample JavaScript Plugin', - - onEventAsync: function (gameEvent, server) { - }, - - onLoadAsync: function (manager) { - }, - - onUnloadAsync: function () { - }, - - onTickAsync: function (server) { - } -}; -``` -#### Required Properties -- `author` — [string] Author of the plugin (usually your name or online name/alias) -- `version` — [float] Version number of your plugin (useful if you release several different versions) -- `name` — [string] Name of your plugin (be descriptive!) -- `onEventAsync` — [function] Handler executed when an event occurs - - `gameEvent` — [parameter object] Object containing event type, origin, target, and other info (see the GameEvent class declaration) - - `server` — [parameter object] Object containing information and methods about the server the event occured on (see the Server class declaration) -- `onLoadAsync` — [function] Handler executed when the plugin is loaded by code - - `manager` — [parameter object] Object reference to the application manager (see the IManager interface definition) -- `onUnloadAsync` — [function] Handler executed when the plugin is unloaded by code (see live reloading) -- `onTickAsync` — [function] Handler executed approximately once per second by code *(unimplemented as of version 2.\*)* - - `server` — [parameter object] Object containing information and methods about the server the event occured on (see the Server class declaration) -### Live Reloading -Thanks to JavaScript's flexibility and parsability, the plugin importer scans the plugins folder and reloads the JavaScript plugins on demand as they're modified. This allows faster development/testing/debugging. - ---- -### Misc -#### Anti-cheat -This is an [IW4x](https://iw4xcachep26muba.onion.link/) only feature (wider game support planned), that uses analytics to detect aimbots and aim-assist tools. -To utilize anti-cheat, enable it during setup **and** copy `_customcallbacks.gsc` from `userraw` into your `IW4x Server\userraw\scripts` folder. - -The anti-cheat feature is a work in progress and as such will be constantly tweaked and may not be 100% accurate, however the goal is to deter as many cheaters as possible from IW4x. -#### Database Storage -By default, all **IW4MAdmin** information is stored in `Database.db`. - -Should you need to reset your database, this file can simply be deleted. -Additionally, this file should be preserved during updates to retain client information. - -Setting the `ConnectionString` and `DatabaseProvider` properties in `IW4MAdminSettings.json` -will allow **IW4MAdmin** to use alternate methods for database storage +## Explore the [wiki](https://github.com/RaidMax/IW4M-Admin/wiki) to find more information.