courierfilter(8)


NAME

   courierfilter - Courier mail filters

SYNOPSIS

   courierfilter [[start] | [stop] | [restart]]

   filterctl [[start] | [stop]] [filter]

DESCRIPTION

   The filterctl commands install or uninstall global mail filters. Global
   mail filters are used to selectively block unwanted mail. More than one
   mail filter can be enabled at the same time. Two filters -
   dupfilter(8)[1] and courierperlfilter(8)[2] - are provided as examples
   for writing mail filters.

   courierfilter start runs all mail filters that have been installed by
   filterctl.  courierfilter stop shuts down all running mail filters.
   After courierfilter start, any filterctl commands take effect
   immediately. After courierfilter stop any filterctl commands will take
   effect at the next courierfilter start.

   courierfilter restart signals the running courierfilter to reread its
   configuration files. This is normally done automatically, by filterctl.

   If any mail filter is installed, the mail filter must be running in
   order for any mail to be processed. Mail filters are assumed to be
   empowered to enforce system-wide mail policies, so if an installed mail
   filter is not running then mail will not be accepted by the system.
   Note that mail will not be rejected, if possible. Every attempt will be
   made to send a temporary error code to an external mail system, asking
   it to try again later.

   For this reason, you should modify your system boot script to run
   courierfilter start as soon as possible, and run courierfilter stop
   during the final portion of your system shutdown script. It is not
   necessary to run courierfilter if you do not install a mail filter with
   filterctl.

MAIL FILTER IMPLEMENTATION

   This section explains how mail filters are implemented, and how to
   write a new global mail filter.

   Available mail filter binaries are located in the directory
   /usr/lib/courier/filters. The filterctl script looks in this directory
   to see which mail filters are available to be installed. Installing a
   mail filter consists of simply creating a soft link from the directory
   /etc/courier/filters/active to its corresponding binary in
   /usr/lib/courier/filters. The courierfilter start command simply reads
   /etc/courier/filters/active and runs every program in this directory.

   The filterctl script sends a HUP signal to courierfilter after
   installing or uninstalling a filter.  courierfilter will reread the
   contents of /etc/courier/filters/active then start or stop individual
   mail filters.

   After starting, an individual mail filter must create a filesystem
   domain socket in one of two directories: /var/lib/courier/filters or
   /var/lib/courier/allfilters. The name of the socket should be the same
   as a name of the filter, and the mail filter must make sure to remove
   any socket by the same name in the other directory. For various silly
   reasons, the recommended implementation is to create
   /var/lib/courier/filters/.NAME or /var/lib/courier/allfilters/.NAME
   (after making sure that it doesn't exist) then rename .NAME to NAME.

   After initializing the socket, the mail filter must then close its file
   descriptor #3. File descriptor 3 is inherited by every mail filter
   that's executed by the courierfilter start command. The mail filter's
   file descriptor 3 is connected to the write end of a pipe, which may be
   relevant to certain ways of implementing the closing of the file
   descriptor, for instance in Perl where you may be forced to pseudo-open
   the descriptor (in write mode) before closing it. The courierfilter
   start command will not exit until every started mail filter closes its
   file descriptor 3. This allows for all mail filters to orderly
   initialize themselves before courierfilter start command returns.

   All mail filters also inherit a pipe on standard input, and must
   terminate when the pipe is closed. Mail filters must simultaneously
   listen for new connections on the mail filter socket, and for their
   standard input to close.

   The mail filter receives a new connection on its socket for every
   message that needs to be filtered. After establishing a connection, the
   mail filter will immediately read the following information from the
   new socket:

   A pathname to a file containing the contents of the message.

   One or more pathnames to control files for this message.

   Each pathname is terminated by a single newline character. The last
   pathname is followed by a second newline character. The pathnames may
   either be relative pathnames to /usr or absolute pathnames, depending
   on the system configuration.

   The mail filter is free to judge the message's worthiness by reading
   its contents and/or control file(s) as soon as a second consecutive
   newline character is received. The final verdict is rendered by writing
   back a result code on the same socket. The result code follows the same
   format as regular SMTP replies (even though the message may not have
   been received via SMTP), and can be used to communicate acceptance,
   temporary failure, or a permanent failure. If it's a failure, then the
   text portion of the result code will be used, if possible. The result
   code may be a multiline response, just like a regular SMTP reply. The
   mail filter must immediately close the connection after writing the
   result code. After closing the socket the mail filter must then proceed
   to wait for another connection request on the original listening
   socket.

   The mail filter can be multithreaded or multitasked, and can accept
   multiple connections simultaneously. When its standard input is closed
   the mail filter should stop accepting new connections and wait for any
   existing connections to be closed, prior to exiting.

   Global mail filters must be EXTREMELY resilient to runtime failures.
   Since mail will not be processed if an installed mail filter is not
   running, if a mail filter crashes it will effectively shut down the
   mail server. Currently courierfilter does not attempt to restart mail
   filters which crash.

MAIL FILTER INVOCATION

   The system administrator defines what mail gets filtered by editing the
   contents of the enablefiltering configuration file in /etc/courier.
   This configuration file contains a list of mail sources that should be
   filtered, like esmtp or local. See courier(8)[3] for more information.
   A default /etc/courier/enablefiltering file is installed that specifies
   only the esmtp mail source as subject to filtering.

   A message is not subject to filtering if its source is not listed in
   /etc/courier/enablefiltering. Otherwise the following rules apply.

   Certain mail destinations have the ability to selectively whitelist
   arbitrary messages. For example, local mail recipients have the ability
   to selectively whitelist individual messages, provided that a local
   mail filter (independent of any global mail filter) is installed that
   implements the maildrop filtering API[4].

   New messages are filtered by connecting to every socket in
   /var/lib/courier/filters and/or /var/lib/courier/allfilters, one at a
   time. All mail filters must accept the message, for it to be accepted
   by Courier. If a socket exists but a connection cannot be established
   then the message is not accepted, and a temporary failure indication is
   returned. That's why no mail will be accepted unless all installed mail
   filters are running.

   Mail recipients that did not whitelist the sender, via the maildrop
   API, will have their mail filtered against everything in
   /var/lib/courier/filters and /var/lib/courier/allfilters. Mail to
   recipients that whitelisted the sender, or mail to destinations that do
   not use a maildrop API-compatible filter, will be filtered only against
   the contents of /var/lib/courier/allfilters.

   This gives system administrators a choice whether to install selective,
   or mandatory mail filters, or a combination of both.

BUGS

   Many filesystem domain socket implementation are buggy.

   Handling of crashed mail filters could be improved.

FILES

   /usr/lib/courier/filters
       Available mail filters.

   /etc/courier/filters
       Miscellaneous configuration files.

   /etc/courier/filters/active
       Installed mail filters.

   /etc/courier/enablefiltering
       Which mail sources to filter.

   /var/lib/courier/allfilters
       Mandatory filters.

   /var/lib/courier/filters
       Optional filters.

SEE ALSO

   localmailfilter(7)[4], courier(8)[3], dupfilter(8)[1],
   ratefilter(8)[5], courierperlfilter(8)[2].

AUTHOR

   Sam Varshavchik
       Author

NOTES

    1. dupfilter(8)
       [set $man.base.url.for.relative.links]/dupfilter.html

    2. courierperlfilter(8)
       [set $man.base.url.for.relative.links]/courierperlfilter.html

    3. courier(8)
       [set $man.base.url.for.relative.links]/courier.html

    4. maildrop filtering API
       [set $man.base.url.for.relative.links]/localmailfilter.html

    5. ratefilter(8)
       [set $man.base.url.for.relative.links]/ratefilter.html





Opportunity


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.





Free Software


Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.


Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.





Free Books


The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.


Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.





Education


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.


Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.