Mask item

In the configuration file there are various places where you can use a mask, match or except. These can be used to match on hosts or IP addresses, but you can also use advanced matching criteria to match users based on if webirc is being used, services account name, the country or ASN (as found by GeoIP), SSL/TLS, certificate fingerprint, reputation score, etc.

The mask item can be used in: allow::mask, ban user::mask, require authentication::mask, oper::mask, except ban::mask, tld::mask, vhost::mask, link::incoming::mask, deny channel::mask, allow channel::mask, connthrottle::except, blacklist::except, set::restrict::commands::except, set::antimixedutf8::except and set::antirandom::except

One or more mask entries

If you only need to match 1 host or IP entry then you can use the simple variant, eg:

    mask 127.0.0.1;

If you want to match multiple items, or if you just prefer this style, then you can use a list:

    mask { *.example.net; *.example.com; }

IP matching dangers

If you want to match an IP, don't make the mistake of using mask 192.168.*; because that would also match people with a hostname of 192.168.example.net.

For IP addresses it is recommended to use: mask { ip 192.168.*; }. Or you can use CIDR notation: mask 192.168.0.0/16;

Advanced matching criteria

You can also match on things other than hostname or IP (same fields as in a security-group block):

mask {
        /* Match people based on ANY of these criteria (OR) */
        mask { <mask>; };
        ip { <ip>; };
        identified <yes|no>;
        webirc <yes|no>;
        websocket <yes|no>;
        tls <yes|no>;
        reputation-score <value>;
        connect-time <timevalue>;
        security-group { <list>; };
        account { <list>; };
        country { <list>; };
        asn { <list>; };
        realname { <list>; };
        certfp { <list>; };
        channel { <list>; };
        destination { <list>; };
        rule "<crule>";

        /* Optionally EXCLUDE people based on this (even if they matched above) */
        exclude-mask { <mask>; };
        exclude-ip { <ip>; };
        exclude-identified <yes|no>;
        exclude-webirc <yes|no>;
        exclude-websocket <yes|no>;
        exclude-tls <yes|no>;
        exclude-reputation-score <value>;
        exclude-connect-time <timevalue>;
        exclude-security-group { <list>; };
        exclude-account { <list>; };
        exclude-country { <list>; };
        exclude-asn { <list>; };
        exclude-realname { <list>; };
        exclude-certfp { <list>; };
        exclude-channel { <list>; };
        exclude-destination { <list>; };
        exclude-rule "<crule>";
}

The items are as follows:

• mask: list of masks that would result in a match, like *.example.net
• ip: list of IP addresses that would result in a match, eg 127.* or using CIDR notation 127.0.0.0/8.
• identified: if set to yes, then if the user is identified to Services then it is considered a match.
• webirc: if set to yes, then if the user comes from a WEBIRC gateway then it is considered a match.
• websocket: if set to yes, then if the user uses WebSockets then it is considered a match. (Requires UnrealIRCd 6.0.7 or later)
• tls: if set to yes, then if the user is using a SSL/TLS connection then it is considered a match.
• reputation-score: if set to a value, like 10, then if the user has a reputation score of this value or higher, it is considered a match. You can also use <10 to say match on a score of below 10.
• connect-time: if set to a time value, like 300 (seconds) or 5m (5 minutes), then if the user has been connected for longer than this time, it is considered a match. You can also use a value like <5m to say less than 5 minutes.
• security-group: this is a match if any of the security groups in this list match.
• account: list of account name(s) that would result in a match, eg: account { TrustedAccount1; TrustedAccount2; }
• country: list of country codes that would result in a match, eg: country { NL; BE; UK; }
• asn: list of AS numbers, eg: asn { 64496; 64497; 64498; }
• realname: list of realnames (gecos) that would result in a match, eg: realname "*Bot*";
• certfp: list of certificate fingerprints (sha256) that would result in a match, eg: certfp "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
• channel: one or more channels the user can be in, optionally prefixed by symbols like ~&@%+ for matching status. Example: channel "@#main"; /* all ops in #main */. (Requires UnrealIRCd 6.1.2 or later)
• destination: the destination (client/channel) of the command, but only at places where this is supported. Currently this can be used in Restrict commands to bypass channel-message, for example. (Requires UnrealIRCd 6.1.7 or later)
• rule: a Crule such as rule "!inchannel('#main') && (online_time()<180 || reputation()<50)";. (Requires UnrealIRCd 6.1.2 or later)
• Other Extended server bans (from 3rd party modules too) can expose more values

Matching rules:

• Any items set to no mean the check will be skipped (ignored).
• Any items set to yes that are true mean the result is a match. Only 1 item that is set to yes needs to match! (But.. see next..)
• If any of the exclude- items match then the final result is NOT a match, even if other things matched.

Examples

By account

allow {
    mask {
        account TrustedUser;
        // or: account { TrustedUser; OtherUser; YetAnother; }
    }
    class clients;
    maxperip 10;
}

By country

/* Spanish MOTD for Spanish speaking countries */
tld {
	mask { country { ES; AR; BO; CL; CO; CR; DO; EC; SV; GT; HN; MX; NI; PA; PY; PE; PR; UY; VE; } }
	motd "ircd.es.motd";
	rules "ircd.es.rules";
}

Negative matching

Most people would use only normal (positive) matching, such as eg 127.*. However, it's also possible to do negative matches, such as: !192.168.*.

If you use negative matching then the rules are as follows:

• If all your entries use negative matching then we match by default, such as with mask { !192.168.*; !10.*; }:
  • 192.168.1.1: not a match
  • 10.1.1.1: not a match
  • Anything else: match!
• If you mix both positive and negative matches then we do not match by default, example: mask { *.com; !irc1.*; !irc2.*; }:
  • irc1.example.com: not a match
  • irc2.example.com: not a match
  • irc3.example.com: match!
  • anything else: not a match