Fetchmail notification IMAP plugin for Dovecot
==============================================

Description
-----------
fetchmail_wakeup is a plugin for Dovecot 1.1, 1.2 [both deprecated], and 2.x
* Versions 1.x are intended to be used with dovecot 1.x
* Versions 2.x are targetted towards dovecot 2.x.
* Versions 2.2.x give up compatibility with dovecot < 2.1
 
By default, it intercepts the IMAP commands to fetch mail from an upstream server:
- STATUS: client polls for new mail
- IDLE:   client tells server to push new mail
- NOOP:   client allows server to notify on new mail
- NOTIFY: client tells server to inform on specific events
and tries to wake up a running fetchmail daemon before performing
the command.

fetchmail_wakeup supports two different ways of waking up a fetchmail
daemon:
- sending the USR1 signal to a PID stored in the first line of a PID file
- executing a command

As both, the PID file and the command to execute, can be configured in
Dovecot's configuration file dovecot.conf, you are not restricted to
fetchmail, but can execute or send a signal to any command you want.

Although some kind of runtime-configurable rate-limiting is supported,
it is limited to being per user and session only.

Hence this module is explicitly not considered suitable for large scale
installations.  But those installations do not rely on fetchmail for pulling
in new mail from a provider anyway.


Copyrights
----------
Copyright (C) 2007 Guillaume Chazarain <[email protected]>
- original version named wake_up_fetchmail.c

Copyright (C) 2009-2023 Peter Marschall <[email protected]>
- adaptions to dovecot 1.1, 1.2 [both deprecated], and 2.x
- rename to fetchmail_wakeup.c
- configuration via dovecot.config


License
-------
LGPL v2.1


Installation
------------
Installation of the plugin is essentially a 3-step process:

1) Configure the paths in Makefile according to your installation
   The relevant variables are:

   * DOVECOT_INCDIR - directory containing dovecot header files
   * DOVECOT_IMAP_MODULEDIR - directory where the plugin shall be installed
   * BINDIR - directory where the helper program shall be installed
   * MAN1DIR - directory where the helper manunal page shall be installed
   * MAN7DIR - directory where the plugin's manual page shall be installed
   * DOVECOT_ETCDIR - directory where dovecot.conf resides
   * FETCHMAIL_PIDFILE - fully qualified path of fetchmail's PID file
   * DEBUG - if you want to see what's going on
   * DOVECOT_PLUGIN_API_2_{0,1} - the plugin API to use

2) Compile the module with the following command line

      make build

3) Then copy the resulting file lib_fetchmail_wakeup_plugin.so
   to the directoy containing the imap plugins of Dovecot.
   This can be achieved using:

      make install

That's it.


Configuration
-------------
After the plugin library is installed and ready to be used, Dovecot's
configuration file, usually /etc/dovecot/dovecot.conf, needs to be adapted
to make Dovecot use the plugin.

This is a 2-step process:

1) Make Dovecot aware of the plugin.
   This happens in dovecot.conf's "protocol imap" section and comprises
   - setting the mail_plugin_dir variable (if not already set)
   - extending the mail_plugins variable by the plugin's name "fetchmail_wakeup"

      protocol imap {
        # ...

        mail_plugins = fetchmail_wakeup
        mail_plugin_dir = /usr/lib/dovecot/modules/imap

        # ...
      }

2) Setting the plugin's configuration options.
   This is done in dovecot.conf's plugin "section".

   fetchmail_wakeup supports four configuration options:
   - fetchmail_commands = COMMAND-LIST
     Comma-separated list of IMAP comamnds to intercept.
     If it is not given, the default is STATUS, IDLE, NOOP, NOTIFY
     as describved above.
   - fetchmail_interval = NUMBER
     Set minimal interval between two fetchmail invocations to NUMBER seconds.
     If it is not given, the interval defaults to 0, which disables rate-limiting.
   - fetchmail_helper = COMMAND
     Execute COMMAND to either start fetchmail (or any other mail fetching tool),
     or to awaken a running fetchmail daemon (or any other mail fetching tool).
   - fetchmail_pidfile = NAME
     Use NAME as the file to read the PID of a running fetchmail instance from,
     and awaken this instance by sending it the SIGUSR1 signal.

   If fetchmail_helper is given, it takes precedence and fetchmail_pidfile
   is ignored.

      plugin {
        # ...

        ## fetchmail_wakeup plugin: awaken fetchmail on IMAP commands

        # IMAP commands to intercept
        # (this setting is optional and defaults to STATUS, IDLE, NOOP, NOTIFY)
        fetchmail_commands = STATUS, IDLE, NOOP, NOTIFY

        # minimal interval (in seconds) between two awakenings of fetchmail
        # (this setting is optional and defaults to 0, disabling rate-limiting)
        fetchmail_interval = 60

        # a helper program to notify fetchmail accordingly
        fetchmail_helper = /usr/bin/awaken-fetchmail

        # pid file of a running fetchmail instance
        fetchmail_pidfile = %h/fetchmail.pid

        # ...
      }

   As the exmaple above shows, it is even possible to use Dovecot's variables
   in the configuration options, and thus awaken fetchmail daemons of multiple
   users with this configuration.

   Starting with dovecot 2.0, the config file can be split into small parts that
   are consolidated automatically by dovecot.
   To support this mode of splitting config files, an example config snippet
   containing the "plugin" part is provided in:

     example-config/conf.d/90-fetchmail_wakeup.conf


Now restart your dovecot daemon and enjoy the comfort of being able to control
fetchmail by simply fetching mail from the server in your IMAP client.


Tests
-----
Original version tested with dovecot-1.0.3
Previous versions tested with dovecot 1.1.13, 1.1.16, various 1.2.x, 2.0.x, 2.1.x, 2.2.9 versions
Current version tested with dovcecot 2.3.18


GIT archive structure
---------------------
dovecot-fetchail's git archive consists of 3 branches:
* original: contains the original import of Guillaume's file
	wake_up_fetchmail.c
* master: contains the main upstream development branch
	Note: until upstream/1.1.1 this branch was called upstream
* debian: contains the extensions to create a Debian package
	using git-buildpackage