Name:	mod_filter
Purpose:	Flexible filtering by server policy
Author:	Magnus Henoch
Type:	Module
Requirements:	ejabberd (works in ejabberd 0.9.8, 2.0.x and 2.1.x)
Download:	Source code: Knobo's github repo (for ejabberd 13+). Source code: Bugzilla. Binary: mod_filter-216-r12b5.zip (2010-05-20 version for ejabberd 2.1.6 with Erlang/OTP R12B-5).

This module allows the admin to specify packet filtering rules using ACL and ACCESS.

Install

1. Download the updated mod_filter.erl from Bugzilla and copy to ejabberd/src.
2. Add the module to the list of modules on ejabberd.cfg:

   {modules, [
     ...
     {mod_filter, []},
     ...
   ]}.

3. Add to ejabberd.cfg the default ACCESS configuration:

   {access, mod_filter, [{allow, all}]}.
   {access, mod_filter_presence, [{allow, all}]}.
   {access, mod_filter_message, [{allow, all}]}.
   {access, mod_filter_iq, [{allow, all}]}.
   

   Then modify those ACCESS rules to your needs. You can see examples below.
4. Recompile and restart ejabberd.

Configuration examples

The configuration of rules is done using ejabberd's ACL and ACCESS, so you should also study the corresponding section on ejabberd guide. This are examples that may help you to understand how it works.

Example 1

%% Admins can send anything.  Others are restricted in various ways.
{access, mod_filter, [{allow, admin},
 		      {restrict_local, local},
 		      {restrict_foreign, all}]}.

%% Local non-admin users can only send messages to other local users.
{access, restrict_local, [{allow, local},
			  {deny, all}]}.
%% Foreign users can only send messages to admins.
{access, restrict_foreign, [{allow, admin},
 			    {deny, all}]}.

Example 2

On this example, the users of a private vhost (example3.org) can only chat with themselves, so that particular vhost will have no connection to the exterior. The other vhosts on the server are completely unrestricted. The administrators are also unrestricted.

% This ejabberd server has three virtual hosts
{hosts, ["example1.org", "example2.org", "example3.org"]}.

% This ACL will match any user or service (MUC, PubSub...) hosted on example3.org
{acl, ex3server, {server_glob, "*example3.net"}}.

% The main mod_filter rule allows any admin, but restricts example3 and the rest of packets
{access, mod_filter, [{allow, admin},
                      {restrict_ex3, ex3server},
                      {restrict_nonex3, all}]}.

% This rule, which applies to packets sent from Ex3 non-admin users,
% allows packets sent to Ex3 server (packets internal to the vhost) and denies anything else.
{access, restrict_ex3, [{allow, ex3server},
                        {deny, all}]}.

% This rule, which applies to the rest of packets (the ones that are not sent from Ex3),
% allows all packets to admins (allowing replies to stanzas from Ex3 admins),
% denies all other access to Ex3, and allows access to anything else.
{access, restrict_nonex3, [{allow, admin},
                           {deny, ex3server},
                           {allow, all}]}.

Example 3

Allow just some MSN users (romeo and juliet) using the transport msn.example.com to comunicate with the users of the server.

{acl, good_msn_users, {user, "romeo%hotmail.com", "msn.example.com"}}.
{acl, good_msn_users, {user, "juliet%hotmail.com", "msn.example.com"}}.
{acl, good_msn_users, {user, "", "msn.example.com"}}.
{acl, msn_users, {server_glob, "msn*"}}.

{access, mod_filter, [
  % Filter incoming messages; allow only good messages
  {allow, good_msn_users},
  {deny, msn_users},
  % Filter the rest, including outgoing messages
  {filter_msn, all}
]}.

{access, filter_msn, [
  % Users can send messages to good MSN users
  {allow, good_msn_users},
  % but not to other MSN users
  {deny, msn_users},
  % All non-MSN traffic is allowed
  {allow, all}
]}.

Example 4

This server has two virtual hosts, one is typical and the other has only anonymous users. The anonymous users cannot send or receive presence stanzas from outside their vhost.

{hosts, ["localhost", "anon.localhost"]}.

{auth_method, [internal]}.
{host_config, "anon.localhost", [{auth_method, anonymous},
                                 {anonymous_protocol, both}]}.

{acl, anon_user, {server_glob, "*anon.localhost"}}.

{access, mod_filter, [{allow, all}]}.

{access, mod_filter_presence, [{allow, admin},
                      {restrict_anon, anon_user},
                      {restrict_no_anon, all}]}.
{access, restrict_anon, [{allow, anon_user}, {deny, all}]}.
{access, restrict_no_anon, [{allow, admin}, {deny, anon_user}, {allow, all}]}.

{access, mod_filter_message, [{allow, all}]}.
{access, mod_filter_iq, [{allow, all}]}.

Example 5

This server has three virtual hosts. The first and second are incommunicated between them. The admins do not have such restriction.

{hosts, ["domain1.localhost", "domain2.localhost", "domain3.localhost"]}.

{acl, domain1, {server_glob, "*domain1.localhost"}}.
{acl, domain2, {server_glob, "*domain2.localhost"}}.

{access, mod_filter, [{allow, admin},
                      {restrict_dom1, domain1},
                      {restrict_dom2, domain2},
                      {allow, all}]}.
{access, mod_filter_presence, [{allow, admin},
                      {restrict_dom1, domain1},
                      {restrict_dom2, domain2},
                      {allow, all}]}.
{access, mod_filter_message, [{allow, admin},
                      {restrict_dom1, domain1},
                      {restrict_dom2, domain2},
                      {allow, all}]}.
{access, mod_filter_iq, [{allow, admin},
                      {restrict_dom1, domain1},
                      {restrict_dom2, domain2},
                      {allow, all}]}.

{access, restrict_dom1, [{allow, domain1},
                        {deny, all}]}.
{access, restrict_dom2, [{allow, domain2},
                        {deny, all}]}.

Comments

This module has been superficially tested. Its performance impact is so far unknown. It is a bit tricky to configure.

Have you tried this module? Did it work well for you? Did you do any benchmarks to see how it affects performance? Is there something that should be changed?

In any case, I would like to know. My Jabber ID is legoscia@jabber.cd.chalmers.se.

Related Links

• Drop messages based on "from" or "to" headers