OnCentralizedBanCheck
OnCentralizedBanCheck is called while the server runs its centralized ban check for an incoming connection, before the result decides whether the client may proceed past authentication.
object OnCentralizedBanCheck(Network.Connection connection)Parameters
| Parameter | Type | Description |
|---|---|---|
connection | Network.Connection | The Network.Connection of the client that is being checked against the centralized ban database. It identifies the joining player but is not a BasePlayer, so you must resolve a player or user id from it if you need one. |
Return value
Returning any non-null value stops the auth coroutine, which prevents the centralized ban check from completing its normal flow for that connection. Returning null lets the coroutine continue and the vanilla centralized ban logic decides the outcome as usual.
How it works
The hook fires inside the Auth_CentralizedBans coroutine's MoveNext, which the server runs as part of authentication for a connecting client. That coroutine is what contacts the centralized ban service and decides whether the connection is allowed to continue; Oxide calls OnCentralizedBanCheck at the top of each step with the connection being checked. Because it runs during the auth coroutine, the player object may not exist yet and the connection can be in any intermediate state.
Use connection to inspect the login: connections expose the Steam id and the username of the incoming client, which lets you match against your own data. The parameter is the only argument, and declaring the hook with that exact type is the reliable form. If you need a player object, wait until OnPlayerConnected or resolve the user by id instead of expecting BasePlayer here.
This is a niche hook: it runs per connection attempt, not per loot, damage or tick event, so it is a reasonable place to make allow/block decisions tied to your own server-side ban lists or external lookup data you persist in oxide/data.
Example plugin: Block connections from a locally maintained watchlist
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Central Ban Watchlist", "RustPluginGenerator", "1.0.0")]
[Description("Blocks connections from a locally maintained Steam id watchlist during the centralized ban check.")]
public class CentralBanWatchlist : RustPlugin
{
private const string PermManage = "centralbanwatchlist.manage";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Blocked Steam IDs")]
public List<string> BlockedSteamIds = new List<string>();
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new Exception();
}
catch
{
PrintWarning("Configuration file is invalid, using defaults");
LoadDefaultConfig();
}
SaveConfig();
}
protected override void SaveConfig() => Config.WriteObject(config);
protected override void LoadDefaultMessages()
{
lang.RegisterMessages(new Dictionary<string, string>
{
["Denied"] = "You are not allowed to connect to this server.",
["Syntax"] = "Usage: watchlist ban <steamid> | watchlist unban <steamid> | watchlist list",
["Added"] = "Added {0} to the watchlist.",
["Removed"] = "Removed {0} from the watchlist.",
["NotListed"] = "{0} is not on the watchlist.",
["Empty"] = "The watchlist is empty."
}, this);
}
private string Msg(string key, string userId = null, params object[] args) => string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermManage, this);
}
private object OnCentralizedBanCheck(Network.Connection connection)
{
if (connection == null) return null;
string steamId = connection.userid.ToString();
if (string.IsNullOrEmpty(steamId) || steamId == "0") return null;
foreach (string id in config.BlockedSteamIds)
{
if (string.Equals(id, steamId, StringComparison.OrdinalIgnoreCase))
{
Puts($"Connection from blocked Steam ID {steamId} ({connection.username}) was stopped.");
return true;
}
}
return null;
}
[ChatCommand("watchlist")]
private void CmdWatchlist(BasePlayer player, string command, string[] args)
{
if (player == null || !player.IsAdmin && !permission.UserHasPermission(player.UserIDString, PermManage))
{
player?.ChatMessage(Msg("Denied", player.UserIDString));
return;
}
if (args == null || args.Length == 0)
{
player.ChatMessage(Msg("Syntax", player.UserIDString));
return;
}
string action = args[0].ToLowerInvariant();
if (action == "list")
{
if (config.BlockedSteamIds.Count == 0)
{
player.ChatMessage(Msg("Empty", player.UserIDString));
return;
}
foreach (string id in config.BlockedSteamIds)
player.ChatMessage(id);
return;
}
if (args.Length < 2 || !ulong.TryParse(args[1], out ulong parsedId) || parsedId == 0)
{
player.ChatMessage(Msg("Syntax", player.UserIDString));
return;
}
string target = parsedId.ToString();
if (action == "ban")
{
if (!config.BlockedSteamIds.Exists(x => string.Equals(x, target, StringComparison.OrdinalIgnoreCase)))
config.BlockedSteamIds.Add(target);
SaveConfig();
player.ChatMessage(Msg("Added", player.UserIDString, target));
}
else if (action == "unban")
{
int removed = config.BlockedSteamIds.RemoveAll(x => string.Equals(x, target, StringComparison.OrdinalIgnoreCase));
SaveConfig();
player.ChatMessage(Msg(removed > 0 ? "Removed" : "NotListed", player.UserIDString, target));
}
else
{
player.ChatMessage(Msg("Syntax", player.UserIDString));
}
}
}
}The plugin keeps a configurable list of banned Steam ids in its config file. When OnCentralizedBanCheck fires, it reads the Steam id from the connection and compares it against the list. If the id is present, the hook returns a non-null value, which halts the centralized ban auth coroutine, keeping that connection from getting past the check. The admin command watchlist ban and watchlist unban manage entries and save the config, so the list survives restarts without any external service. Ids are stored as strings and compared case-insensitively.
Common use cases
Enforce your own ban list before vanilla auth finishes
Keep a local list of Steam ids in oxide/data and return a non-null value when the connecting client matches, so the check is cut short for known offenders.
Log suspicious connection attempts
Record each connection attempt's Steam id and username to a data file for review, while always returning null so vanilla behavior is preserved.
Hold connections pending admin review
Maintain a temporary hold list and stop the auth coroutine for matching ids, letting admins decide whether to allow the client a narrow window later.
Pitfalls
No BasePlayer is available
The hook only receives a Connection. Do not declare it with a
BasePlayerparameter and expect Oxide to call it; it will be skipped because the argument is not a player.Return value halts vanilla ban checking
Any non-null return stops the centralized ban coroutine for that connection. If you only want to observe, return
nullexplicitly on every path, including inside early wrappers.Do not block without a clear reason
Denying a connection during auth can leave the client in a confusing state. Keep denials limited to specific ids you have decided to block and log them for review.
Build a plugin with OnCentralizedBanCheck
Describe what should happen and get a compiled plugin that uses this hook.
Edit the prompt on the next screen. 2 free plugins a month, no card.
Last updated Oct 26, 2026. Found a mistake? Email support@rustplugingenerator.com.
Build a plugin with OnCentralizedBanCheck
Generate