The "filter" Module (v4)

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.
enableflags	Boolean	No	Whether to allow regex flags (/pattern/flags) to be used in a filter regular expression.
notifyuser	Boolean	Yes	Whether to notify users that match a block or silent filter that they have matched it.
warnonselfmsg	Boolean	No	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	If defined then the location to write a filter configuration file to.
saveperiod	Duration	5s	The time period between attempts to check whether the filter configuration file needs to be written.
backoff	Number	0s	The value to multiply the saveperiod by every time a save fails. When the save succeeds the period will be reset.
maxbackoff	Duration	0s	The maximum write period that should be allowed even if incremental backoff is enabled.

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_pcre2	Matches using a PCRE 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.

Example Usage

<filteropts engine="glob"
            enableflags="yes"
            notifyuser="yes"
            warnonselfmsg="no"
            filename="filters.conf"
            saveperiod="5s"
            backoff="2"
            maxbackoff="5m">

<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	Exempt registered users from matching this filter.

Example Usage

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

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.