The "filter" Module (v3)

Description

This module adds the /FILTER command which allows server operators to define regex matches for inappropriate phrases that are not allowed to be used in channel messages, private messages, part messages, or quit messages.

Configuration

To load this module use the following <module> tag:

<module name="filter">

<exemptfromfilter>

The <exemptfromfilter> tag defines a target that is exempt from filtering. This tag can be defined as many times as required.

Name Type Default Value Description
target Text None Required! The target to exempt from filtering.
Example Usage
<exemptfromfilter target="#support">

<filteropts>

The <filteropts> tag defines settings about how the filter module should behave. This tag can only be defined once.

Name Type Default Value Description
engine Text None The regular expression engine to use for checking matches.
notifyuser Boolean Yes Whether to notify users that match a block or silent filter that they have matched it.
warnonselfmsg Boolean No New in v3.2.0! Whether to warn server operators instead of applying the assigned punishment when a user sends a message to themself that matches a filter.
filename String None New in v3.10.0! If defined then the location to write a filter configuration file to.
saveperiod Duration 5s New in v3.10.0! The time period between attempts to check whether the filter configuration file needs to be written.

The engine field should be set to the name of a regular expression engine.

The following regular expression engines are included with InspIRCd:

Engine Module Description
glob regex_glob Matches using a glob pattern.
pcre regex_pcre Matches using a PCRE regular expression.
pcre regex_pcre2 Matches using a PCRE2 regular expression.
posix regex_posix Matches using a POSIX regular expression.
re2 regex_re2 Matches using a RE2 regular expression.
stdregex regex_stdlib Matches using a C++11 std::regex regular expression.
tre regex_tre Deprecated! Matches using a TRE regular expression.
Example Usage
<filteropts engine="glob"
            notifyuser="yes"
            warnonselfmsg="no"
            filename="filters.conf"
            saveperiod="5s">

<keyword>

The <keyword> tag defines an inappropriate phrase. This tag can be defined as many times as required.

Name Type Default Value Description
action Text None The action to take when a user does something that matches this filter.
duration Duration 0s (Permanent) If action is set to gline then the duration that users who match filters should be G-lined for.
flags Text * One or more flags that define what type of messages this filter applies to.
pattern Text None The regex pattern to match against.
reason Text None Required! The reason to give to users when they are being punished for doing something that matches this filter.

The action field should be set to one of the following values:

Value Description
block Block the message that matched the filter and inform server operators with the f (filter) snomask.
gline G-line the user that matched the filter.
kill Kill the user that matched the filter.
none Write the match to the log file and take no other action.
shun Shun the user that matched the filter (requires the shun module).
silent Block the message that matched the filter.
warn Allow the message that matched the filter and inform server operators with the f (filter) snomask.
zline Z-line the user that matched the filter.

The flags field should be set to one or more of the following values:

Value Description
* Equivalent to the flags cnoPpq.
c Strip color codes from messages before trying to match against filters.
n Match against NOTICE messages.
o Exempt server operators from matching this filter.
P Match against PART messages.
p Match against PRIVMSG messages.
q Match against QUIT messages.
r New in v3.2.0! Exempt registered users from matching this filter.
Example Usage

The following example assumes that the "glob" regex module is being used.

See the <filteropts> documentation above for more information.

G-lines unprivileged users for saying the phrase "fluffy capybara" in PRIVMSG and NOTICE messages:

<keyword pattern="*fluffy?capybara*"
         flags="nop"
         action="gline"
         duration="1h"
         reason="Fluffy capybaras are too cute for this network!">

Commands

Name Parameter Count Syntax Description
FILTER 1, 4-5 <pattern>
<pattern> <action> <flags> [<duration>] <reason>
Allows server operators to add and remove filters.

Example Usage

The following examples assume that the "glob" regex module is being used.

See the <filteropts> documentation above for more information.

G-lines users for saying the phrase "fluffy capybara" in /PRIVMSG and /NOTICE messages:

/FILTER *fluffy?capybara* gline nop 1h :Fluffy capybaras are too cute for this network

Kills users who have "spam" in their /PART message:

/FILTER *spam* kill coP :Spam is off-topic on ExampleNet

Removes a filter on *fluffy?capybara*:

/FILTER *fluffy?capybara*

Server Notice Masks

Character Description
f Notifications about filter matches on the local server.
F Notifications about filter matches on a remote server.

Statistics

Character Description
s Lists all filters and filter-exempt targets.

Special Notes

Having a high number of filters or having filters which take a long time to match can have significant impact on server performance.

The filter module will never expose the contents of a message that matched a filter to server operators. This is by design and is intended to prevent server operators from covertly snooping on private conversations.