Skip to content

Bans

Jump to bottom
Person8880 edited this page Jan 8, 2016 · 21 revisions

Overview

The bans plugin provides an alternative to the default banning system. Bans are stored in the JSON file associated with the plugin. By default, this file is located in config://shine/plugins/Bans.json.

If you have a bans file from the default NS2 bans system or from DAK, Shine will automatically convert it on first run, just place it as Bans.json in the plugin config directory.

Web bans files can either be the default NS2 BannedPlayers.json format or the Shine bans plugin config format (note that bans must be in the "Banned" sub-table for the Shine format, so just copy the bans config file to your website if you use the Shine format).

Config

To add a ban for a player that's not in your server, you can either use the ingame command sh_banid, or add it to the file manually. A typical ban config file will look like this:

{
    "DefaultBanTime": 60,
    "GetBansFromWeb": false,
    "BansURL": "",
    "BansSubmitURL": "",
    "BansSubmitArguments": {},
    "GetBansWithPOST": false,
    "MaxSubmitRetries": 3,
    "SubmitTimeout": 5,
    "CheckFamilySharing": false,
    "Banned": {
      "123456": {
        "UnbanTime": 1357055089,
        "Name": "Someone",
        "BannedBy": "Person8880",
        "Duration": 3600,
        "Reason": "Griefing."
      },
      "8765432": {
        "UnbanTime": 0,
        "Name": "Someone else",
        "BannedBy": "Person8880",
        "Duration": 0,
        "Reason": "Trolling."
      },
    }
}

If you place bans in the "Banned" table in the same way as "123456" is, you can add bans without touching the game console. Note that the important parts are "UnbanTime" and "Duration". The rest of it is just extra information for you to see what the ban was for and who did it.

If you are loading bans from the web, you can use the default NS2 format to add bans or the format above.

The file should be called "Bans.json" and should be placed in the directory defined as your plugin config directory (default is config://shine/plugins).

Option Description
DefaultBanTime Time in minutes to ban by default if you do not give a time.
GetBansFromWeb If set to true, the ban list will be loaded from the URL given in BansURL.
BansURL URL to get ban data from is GetBansFromWeb is set to true.
BansSubmitURL URL to submit bans and unbans to.
BansSubmitArguments Extra arguments to send in the POST request. For example, a private key to authenticate.
GetBansWithPOST If set to true, then the bans data will be requested using POST and will send the extra keys in "BansSubmitArguments".
MaxSubmitRetries Sets how many times the plugin should retry sending a ban/unban request if it timed out.
SubmitTimeout How long, in seconds, with no response before we consider the ban/unban request to be timed out.
CheckFamilySharing If true and a Steam API key has been provided in BaseConfig.json, then the plugin will check connecting players to see if they're on a family shared account. If so, and the account sharing NS2 to them is banned, they will be kicked out.

Commands

Command Chat Command Arguments Description
sh_ban !ban <player> <duration> <reason> Bans the given player for the given duration and reason. Both duration and reason are optional.
sh_unban !unban <steamid> Unbans the given Steam ID.
sh_banid !banid <steamid> <duration> <reason> Bans the given Steam ID for the given duration and reason. Player does not have to be in the server (though if they are they will be kicked out).
sh_listbans N/A N/A Lists all stored bans to your console.
sh_forcebansync N/A N/A Forces the plugin to request bans from your website.

Web API

To submit bans to your website, you need to setup a script that takes the input the bans plugin gives it, and returns a fixed result.

Bans will be made effective immediately upon running the ban command, it won't wait for the web server. However, if the web server returns a JSON response with:

{
    "success": false
}

then the ban will be removed. Timeouts to the web server will make it retry. If it reaches the max retries with no response, it assumes the ban should stay and won't try again. You'll need to run the command again to get it to the web server if it didn't.

Ban data is submitted as follows:

http://www.yoursite.com/submit.php?bandata={JSON data here}&unban=0&yourextrakeys=stuff

where bandata is the JSON format:

{
    "Name": "Player's name",
    "ID": 654321,
    "Duration": 3600,
    "UnbanTime": 9999999,
    "BannedBy": "Me",
    "BannerID": 123456,
    "Reason": "Witty reason here.",
    "Issued": 900000
}

The UnbanTime and Issued entries are timestamps.

For unbans, data is submitted as follows:

http://www.yoursite.com/submit.php?unbandata={JSON data here}&unban=1&yourextrakeys=stuff

where unbandata is the JSON format:

{
    "ID": 654321,
    "UnbannerID": 123456
}

Note that "UnbannerID" may be 0 for automatic ban removals.

As for bans, return JSON:

{
    "success": true
}

to allow the unban to pass, or set success to false to get it to reinstate the ban.

Web API Example

Kindly provided by Turbine1991.

Example configuration:

{
  "GetBansFromWeb": true,
  "BansURL": "http://LOCATION/Bans.json",
  "GetBansWithPOST": false,
  "BansSubmitURL": "http://LOCATION/handle_ban.php",
  "BansSubmitArguments": {"auth": "CHANGE THIS VALUE", "readable": 1, "filename": "Bans.json"},
  "MaxSubmitRetries": 3,
  "SubmitTimeout": 5,
  "VanillaConfigUpToDate": true,
  "DefaultBanTime": 60,
  "Banned": {},
}

PHP script:

<?PHP
  /*
    Name: Simple ban handler by NoM.
    Description: Handles ban and unban queries for writing a shared ban file using Shine. Please match the config auth key here.
    Parameters:
      auth - String - Mandatory.
      filename - String - Optionally specify the name of the ban file, uses  "Bans.json" by default. (omit quotes)
      readable - Bool - Format the json output format nicely.
    Requirements:
      Shine
      Have your existing Shine "Bans.json" in your web directory.
      Enable write permissions to parent directory & "Bans.json".
      Configure shine's "Bans.json", providing: "GetBansFromWeb", "BansURL", "BansSubmitURL", "BansSubmitArguments" (optional).
  */

  $auth = 'CHANGE THIS VALUE';

  //Sanity check
  if (!isset($_REQUEST['auth']) || ($_REQUEST['auth'] !== $auth))
    die('Invalid auth key.');

  if (!isset($_REQUEST['unban']) || (!isset($_REQUEST['bandata']) && !isset($_REQUEST['unbandata'])))
    die('Missing ban values.');

  //Retrieve data
  $filename = isset($_REQUEST['filename'])? $_REQUEST['filename']: 'Bans.json';
  $request_unban = intval($_REQUEST['unban']); //Handle unban or ban

  $ban_action_data = ($request_unban)? json_decode($_REQUEST['unbandata'], true): json_decode($_REQUEST['bandata'], true);
  $bans_file_readable = isset($_REQUEST['readable']);

  $bans_file = file_get_contents($filename);
  $bans_config_data = json_decode($bans_file, true); //Store the entire data file in object form; Also maintains table integrity
  $bans_data = &$bans_config_data['Banned']; //Retrieve a reference to the actual bans table (shine stores bans in a sub-table)

  //Handle data operation
  $ban_check_id = $ban_action_data['ID'];

  if ($request_unban) {
    if (isset($bans_data[$ban_check_id]))
      unset($bans_data[$ban_check_id]);
  } else {
    unset($ban_action_data['ID']);
    $bans_data[$ban_check_id] = $ban_action_data;
  }

  //Set json write format flag (readable or efficient output)
  $json_format = ($bans_file_readable)? JSON_PRETTY_PRINT: 0;

  //Write & backup
  $filename_temp = $filename.'Temp.json';
  $filename_old = '.'.$filename.'Old.json';

  $file_ban = fopen($filename_temp, 'w');
  fwrite($file_ban, json_encode($bans_config_data, $json_format));
  fclose($file_ban);
  rename($filename, $filename_old);
  rename($filename_temp, $filename);
  chmod($filename, 0664); //Normalise permissions

  //Print result as raw json
  echo '{"success":true}';
?>
Clone this wiki locally