config.yml reference | Kalkan docs

plugins/kalkan/config.yml holds every setting. The in-game menu and the commands rewrite this file when you change something, so it always matches what is running. After editing it by hand, run kalkan reload in the proxy console. If the file has an error, the old settings stay and the console says why.

The default file

This is the file Kalkan writes on first start, as generated by the plugin itself:

# ─────────────────────────────────────────────────────────────
# Kalkan — anti-VPN and anti-bot for Velocity
# Change these from the in-game /kalkan menu; the menu rewrites this file.
# After editing by hand, run in the proxy console: kalkan reload
# ─────────────────────────────────────────────────────────────

# Your Kalkan license key. The jar you download from BuiltByBit carries it and fills this in by itself.
# Without a valid key Kalkan checks nobody. To change it, run in the proxy console: kalkan license <key>
license-key: ""

# MONITOR: nobody is kicked, logins are only recorded as "would kick".  BLOCK: blocked types are kicked at login.
mode: MONITOR

# Your own countries. The home-countries switches below apply to them. Example: ["US", "CA"]
home-countries: []

# true = that type is blocked (in monitor mode: only recorded).
block:
  other-countries:
    vpn: true
    hosting: true    # datacenter / server / cloud
    tor: true
    warp: false       # Cloudflare 1.1.1.1 / WARP
  home-countries:
    vpn: false
    hosting: false
    tor: false
    warp: false

# Country rules decide by the country of the address, whatever the connection type (they follow the mode).
# blocked: nobody joins from these countries.  only: if not empty, ONLY these countries may join.
# Only the 'allow' list gets past them; an address with an unknown country is always let in. Example: blocked: ["CN", "RU"]
country-rules:
  blocked: []
  only: []

# An account that joined on at least 'min-days' different days in the last 'window-days' from a clean
# (home / mobile) address may also join through a VPN. It still has to pass your login plugin.
trusted-players:
  enabled: true
  min-days: 3
  window-days: 60

# Check Bedrock (Floodgate) players too. Floodgate names start with this prefix.
bedrock-check: true
floodgate-prefix: "."

# Tell players with the kalkan.alerts permission in chat (once per IP every 10 minutes).
staff-alerts: false

# If enabled: when 'threshold-per-minute' blocked-type logins arrive within one minute, they are
# blocked for 'duration-minutes', even in monitor mode.
attack-mode:
  enabled: false
  threshold-per-minute: 30
  duration-minutes: 15

# Experimental, log only: the difference between the in-game ping and the TCP round trip
# (a hint for rented home proxies). It never kicks anyone.
ping-probe: true

# Where the data file (kalkan.db) is downloaded from. It needs an active license.
data:
  url: "https://kalkan.teamatlantis.xyz/data/kalkan.db"
  refresh-minutes: 10

# Always allowed: player names (lower case), IPs / CIDRs, ASNs.
allow:
  players: []
  ips: []
  asns: []

# Your own infrastructure (proxies, backends, VPS): never flagged.
infrastructure-ips: []

# If set, an hourly summary and attack alerts go to this Discord webhook.
discord-webhook: ""

# How many days the decision and ping logs (plugins/kalkan/logs) are kept.
log-days: 30

# What a blocked player sees (MiniMessage). Placeholders:
# <type> <fix> <ip> <country> <country_name> <asn> <org> <name>
kick-message:
  - "<#38c1fc>⛨ Kalkan</#38c1fc>"
  - ""
  - "<gray>Your connection was detected as a <#ff0000><type></#ff0000> connection.</gray>"
  - "<gray>Please <#00ff00><fix></#00ff00> and reconnect.</gray>"
  - ""
  - "<gray>If you think this is a mistake, contact the server staff.</gray>"
  - "<dark_gray><ip> • <country> • AS<asn></dark_gray>"

# What a player stopped by a country rule sees. Placeholders: <ip> <country> <country_name> <asn> <org> <name>
country-kick-message:
  - "<#38c1fc>⛨ Kalkan</#38c1fc>"
  - ""
  - "<gray>Joining from <#ff0000><country_name></#ff0000> is closed on this server.</gray>"
  - ""
  - "<gray>If you think this is a mistake, contact the server staff.</gray>"
  - "<dark_gray><ip> • <country> • AS<asn></dark_gray>"

Mode and countries

Key	Default	Meaning
`mode`	`MONITOR`	`MONITOR`: nobody is kicked, matching logins are recorded as would kick. `BLOCK`: matching logins are kicked.
`home-countries`	`[]`	Your own countries (two-letter codes). The `home-countries` switches apply to them; everyone else is “other countries”.
`block.other-countries.vpn` / `hosting` / `tor` / `warp`	`true` / `true` / `true` / `false`	Which connection types are blocked from other countries
`block.home-countries.vpn` / `hosting` / `tor` / `warp`	all `false`	Which connection types are blocked from your countries
`country-rules.blocked`	`[]`	Nobody joins from these countries
`country-rules.only`	`[]`	If not empty, only these countries may join

Exceptions

Key	Default	Meaning
`trusted-players.enabled`	`true`	Regulars may join through a VPN or hosting address
`trusted-players.min-days`	`3`	Clean days needed (1 to 30)
`trusted-players.window-days`	`60`	Within this many days (at least `min-days`, at most 365)
`allow.players`	`[]`	Player names, lower case. Always let in, past country rules too.
`allow.ips`	`[]`	IPs or CIDR ranges. Always let in.
`allow.asns`	`[]`	Network numbers (`16509` or `AS16509`). Always let in.
`infrastructure-ips`	`[]`	Your own proxies, backends and servers: never flagged
`bedrock-check`	`true`	Check Floodgate players too. `false` lets every Bedrock player in.
`floodgate-prefix`	`"."`	How Floodgate player names start

Attack mode and alerts

Key	Default	Meaning
`attack-mode.enabled`	`false`	Turn attack mode on
`attack-mode.threshold-per-minute`	`30`	Blocked logins within one minute that start an attack (at least 5)
`attack-mode.duration-minutes`	`15`	How long blocked types are kicked, even in monitor mode (1 to 240)
`staff-alerts`	`false`	Chat lines for players with `kalkan.alerts`, once per IP every 10 minutes
`discord-webhook`	`""`	Attack alerts and an hourly summary go here

License, data, logs and the probe

Key	Default	Meaning
`license-key`	filled in from your download	Your license key. Change it with `kalkan license <key>`.
`data.url`	Team Atlantis’s data server	Where `kalkan.db` is downloaded from
`data.refresh-minutes`	`10`	How often Kalkan checks for a new data file (2 to 720)
`log-days`	`30`	How long the decision and ping logs are kept (3 to 365)
`ping-probe`	`true`	Experimental, log only: in-game ping vs TCP round trip. Never kicks anyone.

Kick messages

kick-message is what a player stopped by a connection type sees; country-kick-message is for country rules. Both are lists of MiniMessage lines.

Placeholder	Becomes	In
`<type>`	The connection type, for example datacenter or VPN	`kick-message`
`<fix>`	What to do, for example turn off your VPN	`kick-message`
`<ip>`	The player’s address	both
`<country>`	The country code, for example CN	both
`<country_name>`	The country’s English name, for example China	both
`<asn>`	The network number	both
`<org>`	The network’s name	both
`<name>`	The player name	both