Skip to content
Fetchmail notification IMAP plugin for Dovecot
C Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
contrib
example-config/conf.d
ChangeLog
Makefile
README
awaken-fetchmail.1.in
awaken-fetchmail.c
fetchmail_wakeup.7.in
fetchmail_wakeup.c

README

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

Description
-----------
fetchmail_wakeup is a plugin for Dovecot 1.1, 1.2, 2.0, 2.1 & 2.2
Versions 1.x are intended to be used with dovecot 1.x,
while the 2.x versions are targetted towards dovecot 2.x.
 
It intercepts the IMAPv4 commands to fetch mail from the 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,
this module is not considered suitable for large installations.
But those installations do not rely on fetchmail for pulling in
new mail from a provider anyway.


Copyrights
----------
Copyright (C) 2007 Guillaume Chazarain <guichaz@yahoo.fr>
- original version named wake_up_fetchmail.c

Copyright (C) 2009-2013 Peter Marschall <peter@adpm.de>
- adaptions to dovecot 1.1, 1.2, 2.0, 2.1 & 2.2
- 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 six configuration options:
   - fetchmail_interval = NUMBER
     Set minimal interval between two fetchmail invocations to NUMBER seconds.
     If it is not given, the interval defaults to 60.
   - 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 IDLE, NOOP & STATUS commands

        # minimal interval (in seconds) between two awakenings of fetchmail
        # (this setting is optional and defaults to 60)
        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 versions
Current version tested with dovcecot 2.2.9


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

Something went wrong with that request. Please try again.