Config Tutorial
Getting Started
- Download MaxBans and place it in your Server\Plugins folder
- Run your server and shut it down
Default Config
Check Server\Plugins\MaxBans\config.yml, it should look something like this:
version: 2.0
lockdown: false
lockdown-reason: ""
auto-dupeip: false
history-expirey-minutes: 10080 #1 week.
Warnings config section
New in 1.6
warnings:
How long should warnings take to 'expire'?
Set to 0 for never (...Honestly, I believe you should forgive them after a month at most...)
expirey-in-minutes: 4320
This section looks scary, but really isn't... If you're scared,
Just read the actual stuff and skip the comments unless you want to do some tricky things.
What actions should we take when a player receives a warning?
Format is like:
<number of warnings>: 'commands to execute;seperated by semicolons'
Examples:
actions:
1: 'msg {name} You have been warned!'
2: 'strike {name};msg {name} You have angered Zeus!'
3: 'tempban {name} 1 hour Reached Max Warnings. Reasons:\n{reasons}\nBy: {banner}'
Variables allowed:
{name} the name of the player
{ip} the last known IP of the player
{reason} the last reason the player was warned
{reasons} all the reasons (seperated by new lines) for this punishment. Example:
Reason1: "Griefing"
Reason2: "Spamming"
Reason3: "Begging for items"
Now, if I did
3: 'tempban {name} 1 hour Reached Max Warnings:\n{reasons}'
it would disconnect the user with this message:
-------
You have been Temporarily Banned for:
'Reached Max Warnings:
Griefing
Spamming
Begging for items'
By Console. Expires in 1 hour
-------
If the command starts with a /, then the banner will execute the command
Otherwise, the command will be executed by CONSOLE.
You might want to use -s in these commands (To stop them broadcasting messages to players)
actions:
2: '/kick {name} Final Warning: \n{reason}'
3: '/tempban {name} 1 hour Reached Max Warnings:\n{reasons}'
After receiving this many warnings, they will be all deleted.
If 'actions' has an action for a number higher than this, then the action will never be
done... Because this resets it to 0
If you set this to <= 0, then it will be ignored, and warnings will never reset.
max: 3
Should we check that we're running the latest version of MaxBans?
This does NOT update it for you, it just notifies you in the console when
the server boots up if there is a new version available.
update-check: true
default-reason: "Misconduct"
appeal-message: "No appeal website set :("
color:
primary: f
secondary: a
This applies to kick, ban, and anything else.
kick-colors:
0-9,a-f are valid. Also any Bukkit ChatColor is valid (Eg RED, AQUA, DARK_GRAY)
message: f #"You have been banned for:"
reason: a #"Misconduct"
regular: f #"By"
banner: a #"Netherfoam"
time: a #4 hours 59 minutes remaining.
chat-commands:
- me
- say
Should we notify players with maxbans.notify whenever a banned player tries (fails) to join?
notify: true
Should we verify names have the letters (A-Z,a-z,0-9 and _) only and are valid?
filter-names: true
Should we use the DNS blacklist?
dnsbl:
Should we use this? Setting it to false disables DNSBL entirely.
use: true
The DNSBL servers we should use to look up. More servers = Slower results.
Each server takes approx 4 seconds to respond. Use http://dnsbl.info to find
More servers, if you like.
DNSBL results are cached for 1 week, then expire (Are deleted).
This is how MaxBans checks for proxied IPs
1. Have we looked the IP up on DNSBL before, and has it not expired? If so go to 3
2. Start IP lookup, this takes a few seconds...
3. If the IP is not a proxy, stop checking, they're allowed, do not proceed to step 4.
4. Take appropriate action (Kick, notify) if any.
servers:
- bl.spamcop.net
- sbl.spamhaus.org
Should we notify players with maxbans.notify when a player is joining with a proxy IP?
notify: true
Should we kick players who are discovered to have proxy IPs?
kick: false
bungee: false
Sync is an advanced feature of MaxBans.
It only applies to server owners who want to BAN/etc Players using a WEBPAGE, such as PHP Script
Or owners who want two servers to have the SAME banlist!
This option is in BETA! I take no responsibility if it breaks, though I will endeaver to fix it.
sync:
Should we use Sync? Setting this to false disables it entirely :)
use: false
Is this server the Sync server? Otherwise it's a client.
server: false
The host of the Sync server, if this is a client.
host: 127.0.0.1
The port of the Sync server.
port: 2711
The password required to join.
pass: ChangeMeNow
How many times should the Syncer try to ping the SyncServer
Before giving up? Each try is 5 seconds apart... 12 tries = 1 minute.
tries: 120
debug: false
database:
mysql: false
user: root
pass: passwd
host: localhost
port: 3306
name: maxbans
read-only: false
Lockdowns ==
\\
lockdown: false\\
lockdown-reason: ""\\
When the server is in "lockdown" mode, players without maxbans.lockdown.bypass permissions will be kicked. This is good for when bots rapidly join and leave your server trying to cause lag. The lockdown-reason is the message displayed to players trying to log in. This is changed using the command /lockdown [on/off] [Reason] - The default reason is "Maintenance".
Warning System ==
warnings:
How long should warnings take to 'expire'?
Set to 0 for never (...Honestly, I believe you should forgive them after a month at most...)
expirey-in-minutes: 4320
This section looks scary, but really isn't... If you're scared,
Just read the actual stuff and skip the comments unless you want to do some tricky things.
What actions should we take when a player receives a warning?
Format is like:
<number of warnings>: 'commands to execute;seperated by semicolons'
Examples:
actions:
1: 'msg {name} You have been warned!'
2: 'strike {name};msg {name} You have angered Zeus!'
3: 'tempban {name} 1 hour Reached Max Warnings. Reasons:\n{reasons}\nBy: {banner}'
Variables allowed:
{name} the name of the player
{ip} the last known IP of the player
{reason} the last reason the player was warned
{reasons} all the reasons (seperated by new lines) for this punishment. Example:
Reason1: "Griefing"
Reason2: "Spamming"
Reason3: "Begging for items"
Now, if I did
3: 'tempban {name} 1 hour Reached Max Warnings:\n{reasons}'
it would disconnect the user with this message:
-------
You have been Temporarily Banned for:
'Reached Max Warnings:
Griefing
Spamming
Begging for items'
By Console. Expires in 1 hour
-------
If the command starts with a /, then the banner will execute the command
Otherwise, the command will be executed by CONSOLE.
You might want to use -s in these commands (To stop them broadcasting messages to players)
actions:
2: '/kick {name} Final Warning: \n{reason}'
3: '/tempban {name} 1 hour Reached Max Warnings:\n{reasons}'
After receiving this many warnings, they will be all deleted.
If 'actions' has an action for a number higher than this, then the action will never be
done... Because this resets it to 0
If you set this to <= 0, then it will be ignored, and warnings will never reset.
max: 3
This is possibly a confusing section, so I will take a moment to elaborate on how warnings work:
When a user is 'warned', the warning adds to their current list of warnings. Generally, after a defined amount of warnings, the user is tempbanned, or banned completely.
After a certain amount of time, warnings will expire from the users account. Any user may check their warnings using /checkban by default (They can only do this on themselves unless they have permission)
Once a user receives the highest penalty for their warnings (Eg, tempban), their warnings are disregarded from then on. So if there are 3 warnings, and the third is a tempban, then if I receive a fourth, it will penalize me according to the first warning. If I receive a 5th, it will penalize me according to the 2nd. If I receive a 6th, it will tempban me again according to the 3rd warning. In code, this is something like...
Penalty = penalties.get(totalWarnings MOD maxWarnings);
So to recap:
- Warnings are given
- After an amount of warnings, a command is run on the user
- Warnings can expire after time
- Warnings reset after the last penalty
Now,
Expirey-in-minutes is how long a warning should take to expire. 4320 is 3 days. You may use 0 for 'never' (Please don't, you should forgive your users eventually!)
Actions,
These 'actions' are executed, when a user reaches a certain number of warnings. This should NOT go above 'max' (Because that makes no sense!). They are commands.
You may use a few variables, {ip}, {name}, {reason}, {reasons}, {banner}. These will be replaced with appropriate things when the warning is given.
If the command starts with a /, then it will be executed by the person who gave the warning. They will require permission to execute the command that follows, or it will fail. If the command does not start with a /, then the console will execute it.
The numbers are the warning #.. So by default, maxWarns = 3, and action for 2 is kick, action for 3 is tempban. So when a user receives their 1st or 4th warning, they just get a message. When they get their 2nd or 5th warning, they get kicked. When they receive their 3rd or 6th warning, they're tempbanned.
You may execute multiple commands by separating them using semicolons (";").
Default Reason ==
\\
default-reason: "Misconduct"\\
When your staff are too lazy to supply a message, this is the reason the player will be given. Example: "/kick newguy101" will become "/kick newguy101 Misconduct"
Appeal Message ==
\\
appeal-message: "No appeal website set :("\\
When a player is disconnected when they try to connect, they will be told they cannot connect (they're banned), and then this message will be added below it. Supports color codes like &a and &4. Added in 1.2.
Colors & Chat Commands ==
color: primary: f secondary: a This applies to kick, ban, and anything else. kick-colors: 0-9,a-f are valid. Also any Bukkit ChatColor is valid (Eg RED, AQUA, DARK_GRAY) message: f #"You have been banned for:" reason: a #"Misconduct" regular: f #"By" banner: a #"Netherfoam" time: a #4 hours 59 minutes remaining. chat-commands: - me - say
The color is the color of the MaxBans messages. By default, it is white (primary) and light green (secondary). The chat-commands list is a list of all commands that could be used to bypass mutes, for example, essentials uses the command /me <message> to send an "emote" through chat. This is not picked up by normal chat handling, and is a special case - You must put the commands in this list.
The kick-colors define the color of the kick message sections - You can recolour it how you like, by highlighting the time, reason, banner, etc. I personally believe in sticking to White and Green for it (Looks much neater than rainbow apocalypse), or pure white, but the feature was requested.
A diagram for the kick colours is available here: http://dev.bukkit.org/server-mods/maxbans/images/2-disconnection-colors/
Notifications & Name Filtering ==
Should we notify players with maxbans.notify whenever a banned player tries (fails) to join? notify: true Should we verify names have the letters (A-Z,a-z,0-9 and _) only and are valid? filter-names: true
If notify is set to true, when a banned player tries to join, anyone with maxbans.notify as a permission node will be told that the player failed to join. It will highlight the thing that is banned - For example, if they're IP banned but not banned, the message will be: "NewGuy101 (<RED>127.0.0.1) tried to join, but is banned!" - Their IP is red, meaning their IP is banned.
If filter-names is set to true, it will make sure a-z, A-Z and _ are the only allowed characters in a players name. It will also prevent players joining with blank names.
The DNSBL (DNS Blacklist) ==
Should we use the DNS blacklist? dnsbl: Should we use this? Setting it to false disables DNSBL entirely. use: true The DNSBL servers we should use to look up. More servers = Slower results. Each server takes approx 0.5 seconds to respond. Use http://dnsbl.info to find More servers, if you like. DNSBL results are cached for 1 week, then expire (Are deleted). This is how MaxBans checks for proxied IPs 1. Have we looked the IP up on DNSBL before, and has it not expired? If so go to 3 2. Start IP lookup, this takes a few seconds... 3. If the IP is not a proxy, stop checking, they're allowed, do not proceed to step 4. 4. Take appropriate action (Kick, notify) if any. servers: - bl.spamcop.net - sbl.spamhaus.org Should we notify players with maxbans.notify when a player is joining with a proxy IP? notify: true Should we kick players who are discovered to have proxy IPs? kick: false
First of all, DNSBL is kind of advanced - But sure whips those proxies!
What is DNSBL?
DNSBL is a list of proxy and spammer IP's, freely available on the web. The actual website, http://dnsbl.info/ provides details on this, as well as a list of "servers" which you can query. When querying these servers, it returns whether or not the given IP is known as a spammer. Do not simply add all of these servers to the list! The more there are, the more false positives (and innocent players kicked!) that you receive. Also, it wastes time (Even if the lookups are ASync)
- Setting "use" to false, will disable this feature entirely.
- Servers - The list of servers to lookup IP's on. The default two work well enough for me. Adding more will mean more strict, but slower and more false positives!
- notify - This will tell players with maxbans.notify permissions when a player is discovered to be using a proxy.
- kick - Should we kick a player as soon as we discover they're using a proxy?
Now, the first time a player joins from a new IP address, they won't be kicked immediately. They will be logged in for a few seconds, and once the result comes back - If they're found to be using a proxy - they will be kicked/others notified based on the settings. The result of this is remembered for a week, to save having to do many lookups.
Syncer & Bungee==
bungee: false Sync is an advanced feature of MaxBans. It only applies to server owners who want to BAN/etc Players using a WEBPAGE, such as PHP Script Or owners who want two servers to have the SAME banlist! This option is in BETA! I take no responsibility if it breaks, though I will endeaver to fix it. sync: Should we use Sync? Setting this to false disables it entirely :) use: false Is this server the Sync server? Otherwise it's a client. server: false The host of the Sync server, if this is a client. host: 127.0.0.1 The port of the Sync server. port: 2711 The password required to join. pass: ChangeMeNow How many times should the Syncer try to ping the SyncServer Before giving up? Each try is 5 seconds apart... 12 tries = 1 minute. tries: 120 debug: false
- What is the Syncer?
The syncer allows your server to message other Syncer enabled servers when a player is banned. For example if you run a communtiy of servers (Two or more) and you want bans to sync in real-time, you can enable the SyncServer on one (eg, sync.server: true), then put the details of the SyncServer into the second servers config (Password, host, port). If both servers are running off of the SAME database, ALL servers except for one of them should have database.read-only: true in the config, or you will duplicate your bans & more!
More details for the Syncer and SyncServer available here: http://dev.bukkit.org/bukkit-plugins/maxbans/pages/ban-syncing/ (It's complex to some people)
Database Settings ==
\\
database:\\
mysql: false\\
user: root\\
pass: passwd\\
host: localhost\\
port: 3306\\
name: maxbans\\
read-only: false\\
This is a typical database setting for MySQL. At time of writing, there is no way to convert SQLite <-> MySQL. MySQL is also less thoroughly tested (I use SQLite, is why).
- mysql: If this is false, SQLite will be used instead. None of the following settings will be used.
- user: The username to connect to the database as. Usually root.
- Pass: The password for the above username to connect with.
- Host: The IP of the server this is on. "localhost" means the same computer that Bukkit is running on. But you could direct it to a website if you like.
- Port: The port to connect. Most MySQL installs are running on port 3306.
- Name: The name of the database. This must be created BEFORE running MaxBans with MySQL, otherwise the connection will fail.
- Read-Only: This should be false for Servers that don't use the Syncer. For servers that use the Syncer, only one server per database should have this set to false! (Eg, 3 servers run off of the same database, two should have database.read-only: true, and the other it should be false)
End of configuration section.
Comments