-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
179 lines (132 loc) · 6.21 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
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