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.