OnConnectionQueue
OnConnectionQueue is called when a client is handed to the connection queue and before the server decides whether to admit it or keep it waiting.
object OnConnectionQueue(Network.Connection connection)Parameters
| Parameter | Type | Description |
|---|---|---|
connection | Network.Connection | The Network.Connection of the client waiting to enter the server. Use it to read connection.userid, connection.username, connection.ipaddress and connection.ping. |
Return value
Return null to let the normal queue decision run. Returning any non-null value stops the rest of ConnectionQueue.Join for that connection, so the player is never admitted or queued by this call.
How it works
Rust calls this hook from ConnectionQueue.Join, the method that runs every time a connecting client reaches the queue stage. It fires before the server decides whether the player can join immediately (JoinGame) or has to wait because the queue is occupied or the server is full. Because it runs at this early point, connection already carries the client's Steam ID, name and IP, so it is the right place to inspect or act on incoming connections.
The method returns void, so no result is expected; returning a non-null object simply prevents the queue logic that follows from running for that connection. That means a join attempt is not processed, and the player stays outside the server.
You can filter by declaring a more specific type, but Network.Connection is the only object the game passes here, so narrowing it is not useful. Keep the hook fast: it runs for every join attempt, including DDoS retries, and players are already waiting on it. Useful fields are connection.userid, connection.username and connection.ipaddress.
Example plugin: Block connections from banned IP addresses
using System.Linq;
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
namespace Oxide.Plugins
{
[Info("Connection Ip Blocklist", "RustPluginGenerator", "1.0.0")]
[Description("Blocks connections from configured IP addresses at the connection queue")]
public class ConnectionIpBlocklist : RustPlugin
{
private const string PermUse = "connectionipblocklist.use";
private PluginConfig config;
private class PluginConfig
{
[JsonProperty("Blocked IP addresses")]
public List<string> BlockedIps = 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>
{
["NoPermission"] = "You do not have permission to use this command.",
["Usage"] = "Usage: /ipblock add <ip> | remove <ip> | list",
["Added"] = "Blocked IP {0}.",
["Removed"] = "Removed IP {0} from the blocklist.",
["NotBlocked"] = "IP {0} is not on the blocklist.",
["Empty"] = "The blocklist is empty.",
["List"] = "{0} blocked IPs: {1}",
["Rejected"] = "[IpBlocklist] Rejected connection from {0} ({1})"
}, 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(PermUse, this);
}
private object OnConnectionQueue(Network.Connection connection)
{
if (connection == null || string.IsNullOrEmpty(connection.ipaddress)) return null;
if (!config.BlockedIps.Contains(connection.ipaddress)) return null;
PrintWarning(Msg("Rejected", null, connection.ipaddress, connection.username ?? "unknown"));
return true;
}
[ChatCommand("ipblock")]
private void CmdIpBlock(BasePlayer player, string command, string[] args)
{
if (player == null) return;
if (!permission.UserHasPermission(player.UserIDString, PermUse))
{
player.ChatMessage(Msg("NoPermission", player.UserIDString));
return;
}
if (args == null || args.Length == 0)
{
player.ChatMessage(Msg("Usage", player.UserIDString));
return;
}
string action = args[0].ToLower();
if (action == "list")
{
if (config.BlockedIps.Count == 0)
{
player.ChatMessage(Msg("Empty", player.UserIDString));
return;
}
player.ChatMessage(Msg("List", player.UserIDString, config.BlockedIps.Count, string.Join(", ", config.BlockedIps)));
return;
}
if (args.Length < 2)
{
player.ChatMessage(Msg("Usage", player.UserIDString));
return;
}
string ip = args[1];
if (action == "add")
{
if (!config.BlockedIps.Contains(ip)) config.BlockedIps.Add(ip);
SaveConfig();
player.ChatMessage(Msg("Added", player.UserIDString, ip));
}
else if (action == "remove")
{
if (!config.BlockedIps.Remove(ip))
{
player.ChatMessage(Msg("NotBlocked", player.UserIDString, ip));
return;
}
SaveConfig();
player.ChatMessage(Msg("Removed", player.UserIDString, ip));
}
else
{
player.ChatMessage(Msg("Usage", player.UserIDString));
}
}
}
}The plugin keeps a list of blocked IP addresses in its config file. Every time a client reaches the queue, OnConnectionQueue reads connection.ipaddress and compares it with the list. If the address matches, the plugin logs the attempt, replies to nobody (the client is not fully connected yet) and returns a non-null value, which stops the queue from admitting that connection. Admins manage the list with /ipblock add <ip>, /ipblock remove <ip> and /ipblock list, all gated behind connectionipblocklist.use. Config is validated on load and saved on every change so the list survives restarts.
Common use cases
Block IP addresses or countries at the queue
Reject connections from addresses on a ban list before they ever reach the join logic, keeping a persistent list in the plugin config.
Record queue attempts
Store the Steam ID, name and IP of every connection so admins can review who tried to join during an attack or after a ban.
Gate joins by permission or whitelist
Compare
connection.useridagainst a whitelist and refuse the queue step for clients that are not on it.
Pitfalls
The return value blocks joining entirely
A non-null return cancels the rest of the join method, so a player is not queued and not admitted. Only return a value when you really want to refuse that connection.
No chat access for the player yet
The client is not spawned at queue time, so ChatMessage and SendReply have no player to reach. Limit yourself to logging and return values.
Keep the hook cheap
It runs on every connection attempt, including reconnects and attack traffic. Avoid file I/O, loops over the whole entity list or anything that allocates heavily.
Build a plugin with OnConnectionQueue
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 OnConnectionQueue
Generate