From 566faa48e337bb9f79beef26d8d00b7438362a48 Mon Sep 17 00:00:00 2001 From: JunkyDeveloper Date: Wed, 29 Apr 2026 02:28:03 +0200 Subject: [PATCH 1/5] first version --- .../configuration/blocking_banning_ips.md | 45 +++++++++++++++++++ .../commands/overview-commands.md | 0 .../commands/steel-command/dimensions.md | 0 3 files changed, 45 insertions(+) create mode 100644 src/content/docs/guides/configuration/blocking_banning_ips.md create mode 100644 src/content/docs/guides/configuration/commands/overview-commands.md create mode 100644 src/content/docs/guides/configuration/commands/steel-command/dimensions.md diff --git a/src/content/docs/guides/configuration/blocking_banning_ips.md b/src/content/docs/guides/configuration/blocking_banning_ips.md new file mode 100644 index 0000000..a36191a --- /dev/null +++ b/src/content/docs/guides/configuration/blocking_banning_ips.md @@ -0,0 +1,45 @@ +--- +title: Black & White listing IPs +description: Shows how to ban, blacklist, whitelist IPs and which consequences it has. +--- + +# Basic knowledge +Some terms are familiar from Minecraft, but Steel provides more functionality than normal Minecraft for some commands. Steel gives 3 options to control IPs: blacklist, whitelist and banning. These are powerful tools for server owners. + +This documentation is part of the functionality and file storage. If you want to know all commands for this topic you can find it here. +Instead of checking the expire date with every call, Steel checks every minute if an IP ban has expired, so it will not be accurate to the second. + +When Steel starts, it tries to find the file `ip-bans.json`. If it can't find that file, it searches for Minecraft's `banned-ips.json` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. + +## Terminology + +### Blacklist +This controls connections to the server itself. So if an IP is on the blacklist, a device with that IP can't start a connection with that server. That means the client doesn't get any data. The server will be displayed as not running and even if a client tries to connect it will not work. + +### Whitelist +Minecraft allows whitelisting players, so only these can connect. It's the same idea but for IPs. So only clients with an IP in the whitelist can connect to Steel. This can be used for server network setups to allow for example only proxy servers to connect to this Steel server. So a client can't connect directly to this Steel server, only via proxy. + +### Banning +This is the same feature Minecraft has, but with a few extras. So the player gets information. + +## Configuration +The whitelist is located in the `steel-config.json5` with the property `whitelist` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. + +The second file is `ip-bans.json` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. + +For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. This is an example file structure: +```json +{ + "ip": "127.0.0.3", + "created": "2026-04-28 23:42:49 +0000", + "source": "Server", + "expires": "forever", + "reason": { + "text": "Banned by an operator." + } +} +``` +The reason can be also a text component or a simple string. +`Created` and `expires` have the format: `year-month-day hour:minute:second +timezone`. +Additionally, `expires` allows `forever` as an input; this IP ban will never expire. +The source will be the plugin, server, or player that executed the command. \ No newline at end of file diff --git a/src/content/docs/guides/configuration/commands/overview-commands.md b/src/content/docs/guides/configuration/commands/overview-commands.md new file mode 100644 index 0000000..e69de29 diff --git a/src/content/docs/guides/configuration/commands/steel-command/dimensions.md b/src/content/docs/guides/configuration/commands/steel-command/dimensions.md new file mode 100644 index 0000000..e69de29 From 7abbbc1e9fbbfb051331df5fc26e2a39e3f2cde8 Mon Sep 17 00:00:00 2001 From: JunkyDeveloper Date: Wed, 29 Apr 2026 02:35:18 +0200 Subject: [PATCH 2/5] the file should be working --- .../configuration/blocking_banning_ips.md | 42 +++++++++++-------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/src/content/docs/guides/configuration/blocking_banning_ips.md b/src/content/docs/guides/configuration/blocking_banning_ips.md index a36191a..9ae6c1c 100644 --- a/src/content/docs/guides/configuration/blocking_banning_ips.md +++ b/src/content/docs/guides/configuration/blocking_banning_ips.md @@ -9,37 +9,45 @@ Some terms are familiar from Minecraft, but Steel provides more functionality th This documentation is part of the functionality and file storage. If you want to know all commands for this topic you can find it here. Instead of checking the expire date with every call, Steel checks every minute if an IP ban has expired, so it will not be accurate to the second. -When Steel starts, it tries to find the file `ip-bans.json`. If it can't find that file, it searches for Minecraft's `banned-ips.json` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. +When Steel starts, it tries to find the file `ip-bans.json`. If it can't find that file, it searches for Minecraft's `banned-ips.json` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. If a vanilla entry has no reason or an empty one, Steel substitutes the default reason `Your IP was banned`. -## Terminology - -### Blacklist +## Blacklist This controls connections to the server itself. So if an IP is on the blacklist, a device with that IP can't start a connection with that server. That means the client doesn't get any data. The server will be displayed as not running and even if a client tries to connect it will not work. -### Whitelist +## Whitelist Minecraft allows whitelisting players, so only these can connect. It's the same idea but for IPs. So only clients with an IP in the whitelist can connect to Steel. This can be used for server network setups to allow for example only proxy servers to connect to this Steel server. So a client can't connect directly to this Steel server, only via proxy. -### Banning -This is the same feature Minecraft has, but with a few extras. So the player gets information. +## Banning +This is the same feature Minecraft has, but with a few extras. Unlike a blacklist, the TCP connection is accepted normally; the rejection happens once the client tries to join the game. The player is then kicked with a disconnect screen that shows both the ban reason and the expiry date (or `Never` for permanent bans). + +## How the lists interact +The whitelist takes precedence over both the blacklist and the ban list. As soon as the whitelist contains at least one entry, Steel only checks the whitelist: an IP that is on the whitelist is allowed in even if it is also blacklisted or banned, and an IP that is not on the whitelist is rejected even if it is not blacklisted or banned. With an empty whitelist, the blacklist and ban list both apply normally. -## Configuration +## Configuration/Usage The whitelist is located in the `steel-config.json5` with the property `whitelist` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. The second file is `ip-bans.json` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. -For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. This is an example file structure: +For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. The full `ip-bans.json` file has two top-level arrays — `ip_banned` for the metadata-rich ban entries and `blacklisted` for the bare blacklist: ```json { - "ip": "127.0.0.3", - "created": "2026-04-28 23:42:49 +0000", - "source": "Server", - "expires": "forever", - "reason": { - "text": "Banned by an operator." - } + "ip_banned": [ + { + "ip": "127.0.0.3", + "created": "2026-04-28 23:42:49 +0000", + "source": "Server", + "expires": "forever", + "reason": { + "text": "Banned by an operator." + } + } + ], + "blacklisted": ["127.0.0.4"] } ``` The reason can be also a text component or a simple string. `Created` and `expires` have the format: `year-month-day hour:minute:second +timezone`. Additionally, `expires` allows `forever` as an input; this IP ban will never expire. -The source will be the plugin, server, or player that executed the command. \ No newline at end of file +The source will be the plugin, server, or player that executed the command. + +Changes made via commands are kept in memory and only written to disk when the server shuts down cleanly. If the server crashes before that, recent ban or blacklist edits can be lost — run the save command manually if you need them persisted earlier. \ No newline at end of file From be02269f3cf4b3a8b8e4683fc6edc3d60b00ba7c Mon Sep 17 00:00:00 2001 From: JunkyDeveloper Date: Thu, 30 Apr 2026 00:34:34 +0200 Subject: [PATCH 3/5] switch to toml --- .../configuration/blocking_banning_ips.md | 36 ++++++++----------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/src/content/docs/guides/configuration/blocking_banning_ips.md b/src/content/docs/guides/configuration/blocking_banning_ips.md index 9ae6c1c..c2a88da 100644 --- a/src/content/docs/guides/configuration/blocking_banning_ips.md +++ b/src/content/docs/guides/configuration/blocking_banning_ips.md @@ -9,7 +9,7 @@ Some terms are familiar from Minecraft, but Steel provides more functionality th This documentation is part of the functionality and file storage. If you want to know all commands for this topic you can find it here. Instead of checking the expire date with every call, Steel checks every minute if an IP ban has expired, so it will not be accurate to the second. -When Steel starts, it tries to find the file `ip-bans.json`. If it can't find that file, it searches for Minecraft's `banned-ips.json` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. If a vanilla entry has no reason or an empty one, Steel substitutes the default reason `Your IP was banned`. +When Steel starts, it tries to find the file `ip-bans.toml`. If it can't find that file, it searches for Minecraft's `banned-ips.toml` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. If a vanilla entry has no reason or an empty one, Steel substitutes the default reason `Your IP was banned`. ## Blacklist This controls connections to the server itself. So if an IP is on the blacklist, a device with that IP can't start a connection with that server. That means the client doesn't get any data. The server will be displayed as not running and even if a client tries to connect it will not work. @@ -24,26 +24,20 @@ This is the same feature Minecraft has, but with a few extras. Unlike a blacklis The whitelist takes precedence over both the blacklist and the ban list. As soon as the whitelist contains at least one entry, Steel only checks the whitelist: an IP that is on the whitelist is allowed in even if it is also blacklisted or banned, and an IP that is not on the whitelist is rejected even if it is not blacklisted or banned. With an empty whitelist, the blacklist and ban list both apply normally. ## Configuration/Usage -The whitelist is located in the `steel-config.json5` with the property `whitelist` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. - -The second file is `ip-bans.json` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. - -For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. The full `ip-bans.json` file has two top-level arrays — `ip_banned` for the metadata-rich ban entries and `blacklisted` for the bare blacklist: -```json -{ - "ip_banned": [ - { - "ip": "127.0.0.3", - "created": "2026-04-28 23:42:49 +0000", - "source": "Server", - "expires": "forever", - "reason": { - "text": "Banned by an operator." - } - } - ], - "blacklisted": ["127.0.0.4"] -} +The whitelist is located in the `config.toml` with the property `whitelist` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. + +The second file is `ip-bans.toml` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. + +For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. The full `ip-bans.toml` file has two top-level arrays — `ip_banned` for the metadata-rich ban entries and `blacklisted` for the bare blacklist: +```toml +blacklisted = [] + +[[ip_banned]] +ip = "127.0.0.2" +created = "2026-04-29 22:29:23 +0000" +source = "Server" +expires = "forever" +reason = '{"text":"Banned by an operator."}' ``` The reason can be also a text component or a simple string. `Created` and `expires` have the format: `year-month-day hour:minute:second +timezone`. From d7a82537cba266bcf9a67d25506dbfba690eb7fc Mon Sep 17 00:00:00 2001 From: JunkyDeveloper Date: Thu, 30 Apr 2026 10:39:51 +0200 Subject: [PATCH 4/5] catch from @ht06 --- .../docs/guides/configuration/blocking_banning_ips.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/guides/configuration/blocking_banning_ips.md b/src/content/docs/guides/configuration/blocking_banning_ips.md index c2a88da..4b2c944 100644 --- a/src/content/docs/guides/configuration/blocking_banning_ips.md +++ b/src/content/docs/guides/configuration/blocking_banning_ips.md @@ -24,7 +24,13 @@ This is the same feature Minecraft has, but with a few extras. Unlike a blacklis The whitelist takes precedence over both the blacklist and the ban list. As soon as the whitelist contains at least one entry, Steel only checks the whitelist: an IP that is on the whitelist is allowed in even if it is also blacklisted or banned, and an IP that is not on the whitelist is rejected even if it is not blacklisted or banned. With an empty whitelist, the blacklist and ban list both apply normally. ## Configuration/Usage -The whitelist is located in the `config.toml` with the property `whitelist` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. +The whitelist is located in the `config.toml` with the property `whitelisted_ips` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. +It will look like this: +```toml +[server] +# IP addresses allowed to connect to the server. If empty, no whitelist is applied. +whitelisted_ips = ["127.0.0.1"] +``` The second file is `ip-bans.toml` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. From ed9d5e7e577870abf6812b0b4ce66d69df6c0a1a Mon Sep 17 00:00:00 2001 From: JunkyDeveloper Date: Sun, 7 Jun 2026 19:54:57 +0200 Subject: [PATCH 5/5] change to shadowban --- .../configuration/blocking_banning_ips.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/docs/guides/configuration/blocking_banning_ips.md b/src/content/docs/guides/configuration/blocking_banning_ips.md index 4b2c944..d80d091 100644 --- a/src/content/docs/guides/configuration/blocking_banning_ips.md +++ b/src/content/docs/guides/configuration/blocking_banning_ips.md @@ -1,27 +1,27 @@ --- title: Black & White listing IPs -description: Shows how to ban, blacklist, whitelist IPs and which consequences it has. +description: Shows how to ban, shadowbanned, whitelist IPs and which consequences it has. --- # Basic knowledge -Some terms are familiar from Minecraft, but Steel provides more functionality than normal Minecraft for some commands. Steel gives 3 options to control IPs: blacklist, whitelist and banning. These are powerful tools for server owners. +Some terms are familiar from Minecraft, but Steel provides more functionality than normal Minecraft for some commands. Steel gives 3 options to control IPs: shadowbanned, whitelist and banning. These are powerful tools for server owners. This documentation is part of the functionality and file storage. If you want to know all commands for this topic you can find it here. Instead of checking the expire date with every call, Steel checks every minute if an IP ban has expired, so it will not be accurate to the second. When Steel starts, it tries to find the file `ip-bans.toml`. If it can't find that file, it searches for Minecraft's `banned-ips.toml` and loads the data into memory; on the next save, it converts the data to Steel's format so it can be used on the next start. There is also a command to trigger the loading manually. If a vanilla entry has no reason or an empty one, Steel substitutes the default reason `Your IP was banned`. -## Blacklist -This controls connections to the server itself. So if an IP is on the blacklist, a device with that IP can't start a connection with that server. That means the client doesn't get any data. The server will be displayed as not running and even if a client tries to connect it will not work. +## shadowbanned +This controls connections to the server itself. So if an IP is on the shadowbanned, a device with that IP can't start a connection with that server. That means the client doesn't get any data. The server will be displayed as not running and even if a client tries to connect it will not work. ## Whitelist Minecraft allows whitelisting players, so only these can connect. It's the same idea but for IPs. So only clients with an IP in the whitelist can connect to Steel. This can be used for server network setups to allow for example only proxy servers to connect to this Steel server. So a client can't connect directly to this Steel server, only via proxy. ## Banning -This is the same feature Minecraft has, but with a few extras. Unlike a blacklist, the TCP connection is accepted normally; the rejection happens once the client tries to join the game. The player is then kicked with a disconnect screen that shows both the ban reason and the expiry date (or `Never` for permanent bans). +This is the same feature Minecraft has, but with a few extras. Unlike a shadowbanned, the TCP connection is accepted normally; the rejection happens once the client tries to join the game. The player is then kicked with a disconnect screen that shows both the ban reason and the expiry date (or `Never` for permanent bans). ## How the lists interact -The whitelist takes precedence over both the blacklist and the ban list. As soon as the whitelist contains at least one entry, Steel only checks the whitelist: an IP that is on the whitelist is allowed in even if it is also blacklisted or banned, and an IP that is not on the whitelist is rejected even if it is not blacklisted or banned. With an empty whitelist, the blacklist and ban list both apply normally. +The whitelist takes precedence over both the shadowbanned and the ban list. As soon as the whitelist contains at least one entry, Steel only checks the whitelist: an IP that is on the whitelist is allowed in even if it is also shadowbanneded or banned, and an IP that is not on the whitelist is rejected even if it is not shadowbanneded or banned. With an empty whitelist, the shadowbanned and ban list both apply normally. ## Configuration/Usage The whitelist is located in the `config.toml` with the property `whitelisted_ips` which is a simple array of strings with all IP addresses. It can be only edited via the config file so there is only a list command available. @@ -32,11 +32,11 @@ It will look like this: whitelisted_ips = ["127.0.0.1"] ``` -The second file is `ip-bans.toml` which holds the blacklist and the banned IP data. The blacklist is, like the whitelist, a property `blacklisted` and an array of strings which represent IPs; it can be edited via file or commands. +The second file is `ip-bans.toml` which holds the shadowbanned and the banned IP data. The shadowbanned is, like the whitelist, a property `shadowbanned` and an array of strings which represent IPs; it can be edited via file or commands. -For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. The full `ip-bans.toml` file has two top-level arrays — `ip_banned` for the metadata-rich ban entries and `blacklisted` for the bare blacklist: +For banning IPs more options are possible: beyond Minecraft's options, Steel also has the option to give an expire date and reason. This can also be done with commands, more information about which you can find here. The full `ip-bans.toml` file has two top-level arrays — `ip_banned` for the metadata-rich ban entries and `shadowbanned` for the bare shadowbanned: ```toml -blacklisted = [] +shadowbanned = [] [[ip_banned]] ip = "127.0.0.2" @@ -50,4 +50,4 @@ The reason can be also a text component or a simple string. Additionally, `expires` allows `forever` as an input; this IP ban will never expire. The source will be the plugin, server, or player that executed the command. -Changes made via commands are kept in memory and only written to disk when the server shuts down cleanly. If the server crashes before that, recent ban or blacklist edits can be lost — run the save command manually if you need them persisted earlier. \ No newline at end of file +Changes made via commands are kept in memory and only written to disk when the server shuts down cleanly. If the server crashes before that, recent ban or shadowbanned edits can be lost — run the save command manually if you need them persisted earlier. \ No newline at end of file