<cat>Play.Hosting</cat> <title>Centralized Banning</title> # What is it? Centralized banning is a (new!) feature within the Rust dedicated server which allows server owners to build a synchronized, external ban list that can be shared across multiple servers. # How do I use it? You will need a web server (HTTP or HTTPS) which hosts the centralized banning API. We do not have a publicly available implementation of this but it is relatively simple to implement. To enable it on your server, simply set the `server.bansServerEndpoint` convar to your web server API endpoint. For example: ``` server.bansServerEndpoint "https://contoso.com/api/rustBans/" ``` Once set, the Rust dedicated server will query that API endpoint to check if players are banned at the time they join the server. # API details Assuming `server.bansServerEndpoint` is set to something like "https://contoso.com/api/rustBans/", your web server will receive requests like these from the Rust dedicated server. Assuming `server.bansServerEndpoint` is set to something like "https://domain.tld/api/rustBans/", your web server will receive requests like these from the Rust dedicated server. ## GET /api/rustBans/{steamID64} Returns the ban status for a 64-bit SteamID in JSON format. **Note**: The URI for this request is generated by appending the 64-bit SteamID to the value of `server.bansServerEndpoint`, with a forward slash if required. Sample response: ``` { "steamId": "76561197960287930", "reason": "definitely not cheating", "expiryDate": 1608611830 } ``` | Field | Description | | ----- | ----------- | | steamId | The 64-bit SteamID the ban is for. This is used to sanity check that the API implementation is returning the correct bans. | | reason | The reason for the ban. This will be displayed to the player when they connect to the server. | | expiryDate | [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) that sets when the ban expires. This will be used to show the time remaining on the ban to the player when they connect to the server. Values less than or equal to zero indicate that the ban is permanent. | The Rust dedicated server will also check the web server's response code: | Status Code | Meaning | | ----------- | ------- | | 2xx | Success codes (2xx) require the JSON format above to be returned in the response body. | | 404 | Not found indicates that the requested 64-bit SteamID is not banned. | | Other | Redirects should be handled by Unity, but error codes will result in a failure (see `server.bansServerFailureMode` convar in FAQ) | # FAQ ## Will players be kicked from servers when a ban is added to the endpoint? No, centralized banning will only prevent players from entering the server. If you want them kicked from the server immediately then you will need to use the `kick` command on whichever server they are on. ## What happens when the API endpoint is down or not working properly? A message will be logged to the Rust dedicated server console whenever the centralized banning system encounters an error. A separate convar (`server.bansServerFailureMode`) controls what happens to players who failed to be checked: | bansServerFailureMode Value | Meaning | |-----------------------------|---------| | 0 | Players are allowed into the server when an error occurs (message logged in server console) | | 1 | Players are rejected from joining the server when an error occurs (message logged in server console, also visible to player ) | ## Requests to my API endpoint are timing out. What can I do? The default timeout for all centralized banning requests is set to five seconds. This should be more than enough but if it is causing issues then you can adjust it using the `server.bansServerTimeout` convar (the value is in seconds). Keep in mind that the longer the requests take the longer players will need to wait to join your server - try to make your API faster instead of increasing the timeout. ## Do I need to restart my server after changing any of the convars? You do not need to restart your server after changing `bansServerEndpoint`, `bansServerFailureMode`, or `bansServerTimeout`. However, players already on the server will not be kicked when enabling or changing `bansServerEndpoint`.