Anti-flood settings

This page describes the set::anti-flood block, which used to configure nearly all anti flood settings in UnrealIRCd.

IMPORTANT: Below is for UnrealIRCd 5.2.0 and later. For UnrealIRCd 5.0.x see Anti-flood settings (OLD).

= Introduction and default settings = In UnrealIRCd 5.2.0 and later a new style anti-flood block is used. It has three groups:
 * known-users: by default, this are users who are identified to services OR are on an IP that has been connected for over 2 hours in the past X days.
 * unknown-users: all the users that are not known-users
 * everyone: some settings are in this group, they apply to everyone due to technical limitations.

Most anti flood settings are set using rates. For example, a nick-flood setting of  means a maximum of 3 nick changes per 60 seconds.

Below is overview of the block and the default settings. Note that each settings is explained in detail later, further down. set { anti-flood { /* These limits apply to all users, * Only these 4 settings belong here (and only here): */               everyone { connect-flood 3:60; handshake-data-flood { amount 4k; ban-action zline; ban-time 5m; }                       target-flood { channel-privmsg 45:5; channel-notice 15:5; channel-tagmsg 15:5; private-privmsg 30:5; private-notice 10:5; private-tagmsg 10:5; }               }

/* These are the "known users" who (if you use default                * security group settings) are: registered users * who are identified to services, OR have been connected * to UnrealIRCd for longer than 2 hours. */               known-users { nick-flood 3:60; join-flood 3:90; away-flood 4:120; invite-flood 4:60; knock-flood 4:120; max-concurrent-conversations { users 10; new-user-every 15s; }               }

/* Everyone who is not in the known-users group. * These users have lower limits: */               unknown-users { nick-flood 2:60; join-flood 2:90; away-flood 4:120; invite-flood 2:60; knock-flood 2:120; max-concurrent-conversations { users 4; new-user-every 15s; }               }        } }

= Settings that apply to everyone =

connect-flood
This limits the number of connection attempts from each IP to 'count' per 'period' seconds. Default is 3 per 60. This feature is also referred to as connection throttling.

UnrealIRCd also has Connthrottle which will rate limit the number of connection attempts in total (so not per-IP).

Note that connection throttling is an important security measure. It provides primary and secondary protection against DoS, flood and brute force attacks, both for handshake and fully registered connections. If you disable it or set it very permissive (eg 6 per 60 seconds) then you severely degrade these protections.

If you want to exempt one or more IP's from connect-flood, then check out Except ban block and use type connect-flood there.

Example block with the default settings: set { anti-flood { /* These limits apply to all users, * Only these 4 settings belong here (and only here): */               everyone { connect-flood 3:60; }       } }

handshake-data-flood
NOTE: This settings is almost never changed. This flood protection is never hit by real IRC clients.

When a TCP/IP connection is accepted, the client sends some data during the IRC protocol "handshake" such as NICK, username and optionally IRCv3 CAP negotiation and SASL. After this handshake the client comes online. If more than the specified amount of data is sent during the handshake then a specified action is taken. This is a security measure to protect against arbitrary data floods, sending lots of bytes and consuming useless CPU and bandwidth. In all known cases less than 4k (4096 bytes) are sent during the handshake, so this allows us to be quite strict.

Example block with the default settings: set { anti-flood { everyone { handshake-data-flood { amount 4k; ban-action zline; ban-time 5m; }               }        } }

target-flood
This flood countermeasure works differently than all the others. It will limit floods to targets such as channels and persons at a maximum rate. This so, for example a channel, can never see more than X lines per Y seconds.

The goal is to prevent flooding at HIGH rates only. To prevent flooding at such high rates that the client may no longer be capable of handling the traffic in terms of CPU usage (such as leading to a laggy interface) or even bandwidth. This is why the maximum rates are very high. We don't want this to be triggered in normal conditions even for extreme cases, such as channels that have a quiz/trivia bot. Even with this target-flood protection enabled, some IRC clients may still have problems with some types of traffic below the set maximum rate, we only do our best to limit damage to most clients this way.

This countermeasure is NOT for low-rate or medium-rate spamming/floods. If you want more strict channel flood control (and you probably do!), then use the very powerful and customizable channel mode +f as well.

There are 2 possible target types: channels and users. For each of those 2 there are 3 possible message types in IRC: privmsg, notice and tagmsg. Below you can see the default settings:

set { anti-flood { everyone { target-flood { channel-privmsg 45:5; channel-notice 15:5; channel-tagmsg 15:5; private-privmsg 30:5; private-notice 10:5; private-tagmsg 10:5; }               }        } }

When the target-flood limit is hit, we will drop the message. We do not kill the user, because the user who sent the 15th/60th/etc message could be a totally innocent user who only said stop this flood!. This is also why we don't offer a configuration option for killing either, since you may very well end up killing good people.

The limits apply to everyone (including channel operators), the only exception are IRCOps which are exempt if they have the immune:target-flood privilege (all IRCOps do, by default).

This anti-flood feature is handled by the targetfloodprot module which is loaded by default. You can use blacklisting in the configuration file to completely remove this anti-flood feature:

= Settings that apply to groups = The following settings can be different for each security group. In most cases you will have two groups:
 * known-users: identified to services OR are on an IP that has been connected for over 2 hours in the past X days.
 * unknown-users: all the users that are not known-users

The criteria of who falls in known-users and who in unknown-users is decided by the security-group { } blocks. For example, if you want to put all your WEBIRC users in the known-users group, you can do so there.

nick-flood
This limits the number of NICK changes a user can do. The default is 3 per 60 seconds for known-users and 2 per 60 seconds for unknown-users:

set { anti-flood { known-users { nick-flood 3:60; }               unknown-users { nick-flood 2:60; }       } }

join-flood
This settings works slightly different than others. It does not limit all joins to a maximum of X per Y seconds. Instead, this setting limits (re)joins to the same channel to X per Y seconds. Thus, it prevents PART+JOIN'ing the same channel repeatedly. The default is 3 per 90 seconds for known-users and 2 per 90 seconds for unknown-users:

set { anti-flood { known-users { join-flood 3:90; }               unknown-users { join-flood 3:90; }       } }

away-flood
This limits the number of AWAY changes a user can do. The AWAY command is used to mark someone as away or back from away. Usually, these aways+unaways are not very annoying, so by default we allow 4 per 120 seconds for both known-users and unknown-users.

set { anti-flood { known-users { away-flood 4:60; }               unknown-users { away-flood 4:60; }       } }

invite-flood
This limits the number of /INVITE's a user can do. The default is 4 per 60 seconds for known-users and 2 per 60 seconds for unknown-users:

set { anti-flood { known-users { invite-flood 4:60; }               unknown-users { invite-flood 2:60; }       } }

invite-flood
This limits the number of /KNOCK's a user can do (rarely used command to knock on channels [s]he can't join). The default is 4 per 120 seconds for known-users and 2 per 120 seconds for unknown-users:

set { anti-flood { known-users { knock-flood 4:120; }               unknown-users { knock-flood 2:120; }       } }

max-concurrent-conversations
This configures the maximum number of conversations a user can have with other users at the same time. This is a protection measure against spambots who tend to mass  or   many different users within a short period of time.

Let us explain with the default settings: set { anti-flood { known-users { max-concurrent-conversations { users 10; new-user-every 15s; }               }                unknown-users { max-concurrent-conversations { users 4; new-user-every 15s; }               }        } }

A user may message up to max-concurrent-conversations::users different users without any problem. If he/she then messages another user this is only permitted at a rate of 1 every max-concurrent-conversations::new-user-every seconds.

For example, if the user belongs to known-users, then with a users set to 10 and new-user-every set to 15:
 * UnrealIRCd will remember up to 10 users that the user is messaging
 * The user can /MSG the first 10 users without any problem (eg: k1, k2, k3, k4, k5, k6, k7, k8, k9, k10)
 * When trying to send a message to the 11th user (eg: k11) the user will have to wait up to 15 seconds before (s)he can do.
 * Then the user can message the 11th user (k11)
 * If the user then wants to send a message to a 12th user (k12, or even user k1 again which has by now dropped of the active 10 users list) then (s)he has to wait 15 seconds again

Since most users don't actively message many different users within a short period of time, this can be used as a way to detect bots/drones that flood users. The goal is to set the limit high enough for normal users to never experience this limit, yet low enough to be meaningful as a spambot countermeasure.

Also, note that this setting only affects user to user messaging and not messages to channels. This is because it is assumed that channel flood controls can take care of channel flooding.

The default settings are:
 * UnrealIRCd 3.2.x - 4.2.1: 20 users, then new-user-every 15 seconds
 * UnrealIRCd 4.2.2 - 5.0.9.1: 10 users, then new-user-every 15 seconds
 * UnrealIRCd 5.2.x: For known-users: 10 users, new-user-every 15 seconds. For unknown-users: 4 users, new-user-every 15 seconds.