Skip to content

Bans

Jump to bottom
Person8880 edited this page Apr 25, 2021 · 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. It will also keep the vanilla bans file in sync with Shine's in case the mod ever fails to load due to Steam workshop problems, so that your bans are not completely lost.

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 in-game 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,
    "BanSharerOnSharedBan": false,
    "AlwaysBlockFamilySharedPlayers": 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."
      },
    },
    "__Version": "1.6"
}

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.
BanSharerOnSharedBan If true and a Steam API key is provided, any player that is playing through family sharing and then banned will cause the account sharing the game to them to also be banned for the same duration. Combine this with CheckFamilySharing to prevent any further use of the main account to family share.
AlwaysBlockFamilySharedPlayers If true and CheckFamilySharing is enabled (with a Steam API key configured), any player that is playing through family sharing will be prevented from connecting to the server, regardless of whether the player sharing the game with them is banned or not.

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.

Permissions

Permission Description
sh_ban_family_share_immune Makes a user immune to family sharing checks. This means that if CheckFamilySharing is true, the user will not be blocked from connecting if the player sharing the game to them is banned, nor will they be blocked if AlwaysBlockFamilySharedPlayers is true.

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';
  // Handle unban or ban
  $request_unban = intval($_REQUEST['unban']);

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

  $lock_file = fopen($filename.'.lock', 'w+');
  // Lock to prevent concurrent access to the bans file, which could leave it inconsistent.
  if (!flock($lock_file, LOCK_EX)) {
    die('Unable to acquire lock.');
  }

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

  // 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';
  $filename_old = $filename.'.old';

  $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);
  // Normalise permissions
  chmod($filename, 0664);

  // Release lock to allow other processes to update the file again.
  flock($lock_file, LOCK_UN);
  fclose($lock_file);

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