Tip of the day: If you still have users on plaintext port 6667, consider enabling Strict Transport Security to gently move users to SSL/TLS on port 6697.

Central Spamfilter

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

UnrealIRCd.org Central API Services

UnrealIRCd 6.1.2 and later have a central spamfilter feature. You can enable it with: set { central-spamfilter { enabled yes; } }

When enabled, UnrealIRCd will automatically fetch and refresh spamfilter rules from spamfilter.unrealircd.org every hour in the background. The idea is to block large scale spam that affects several IRC networks, or even the IRC community as a whole.

In UnrealIRCd 6.1.3+ we fetch the central spamfilters using your api-key from Central API, if you have one. This restricted-access spamfilter may (later) contain more/better entries than the open-access one (the central spamfilter list that is used if you don't have an API key).

Current status

On Oct 5, 2023 we added the first two rules. This stops some current spam and is used to showcase and test the central spamfilter functionality.

At a later point we will wish to expand the ruleset and (very important) get more people involved who write rules, a better (internal) management system on our side to test, deploy and manage central spamfilters, etc.


Central Spamfilter can be a powerful tool (especially in the future, when we add more rules), but there is also a risk that bad spamfilters can cause problems, such as innocent users being killed. In fact, even otherwise good spamfilters could get innocent users killed, this is especially true for bots that can be instructed to send specific text by users, as they can basically be tricked into saying spamfiltered phrases.

We try to limit problems the following way (this is all fluid and can be changed in the future):

  • First, we do our best to create good spamfilters that will only trigger for the bots/drones/spam that it should affect. Nowadays, UnrealIRCd's Spamfilter has a lot of properties it can use, some go beyond simple text matches.
  • We have different feeds (see set::central-spamfilter::feed), where fast feed users get new spamfilters first and standard feed users only get it after they have been in fast for a while
  • You, as a server admin, can optionally limit actions via set::spamfilter::limit-ban-action (and ::ban-time). You can even set it as low as warn to still get warnings but nobody being killed/glined.
  • Similar to that, we may set rules in central spamfilter with action warn first, rather than going straight for gline.
  • Access to the central spamfilter machine is highly restricted

But even then, as always with spamfiltering (for e-mail too) and with any systems on the internet out there, there is always a chance that something can go wrong. We cannot be held liable for any damage central spamfilter may cause.

Similarly, central spamfilter won't stop all spam. First of all that is impossible. Second, it is not our intention: the (initial) plan is to block large scale spam that affects several IRC networks or even the IRC community as a whole, not to stop spam that is only targeted against one single network.

The ruleset

If you want to see the current central spamfilter rules:


To enable, create a set::central-spamfilter block, like:

set {
        central-spamfilter {
                enabled yes;
                feed standard; // or 'fast' for the fast feed

Here is the complete syntax with all possible options:

set {
        central-spamfilter {
                enabled <yes|no>;
                feed <fast|standard>;
                refresh-time <timevalue>;
                verbose <value>;
                except { .. };
                limit-ban-action <action>;
                limit-ban-time <timevalue>;
  • set::central-spamfilter::enabled defaults to no, set to yes to enable central spamfilter
  • set::central-spamfilter::feed: this tells which central spamfilter feed to use (standard is the default):
    • fast: all new spamfilters are first deployed to the fast feed. If you use this feed you benefit from the new spamfilters early and at the same time help with making sure the spamfilters are good enough, before they end up in the standard feed. Other than new rules, the ones in fast also include the rules from from standard.
    • standard: the spamfilters in this feed have been previously tested in the fast feed for a while and should be good.
  • set::central-spamfilter::refresh-time decides how often to check for updates, the default is 1h (1 hour)
  • set::central-spamfilter::verbose is used for debugging requests/responses
  • set::central-spamfilter::except decides for which users the central spamfilters do not to take any actions, any hits for these users are counted as false positives.
    This currently defaults to except { reputation-score 2006; mask { *.irccloud.com; } } which affects users that have been online for longer than 7 days (unregistered) or 3.5 days (identified to services) in the past month or so, and users who use IRCCloud.
  • set::central-spamfilter::limit-ban-action can be used to limit all the actions of central spamfilters to the specified ban action at most. For example, if you don't trust central spamfilter enough and don't want glines, you can limit it to kill. This does not turn all central spamfilter hits into kills then, some central rules may have 'lighter' rules like block, which will stay stay at 'block', this is why it is called limit-ban-action and not ban-action. Other options if you don't trust central spamfilter enough are block or even just warn.
  • set::central-spamfilter::limit-ban-time can be used to limit the ban time for any *LINES places by central spamfilters. Any ban time in the central spamfilters higher than this will be capped at this value.